A.C.E. 3/ACE CD 3.iso/files/docs/candodoc.lha/CandoPart1.doc

Text File | 1994-11-27 | 159KB | 3,773 lines

                          "The CanDo HowTo Book!"

 The CanDo Manual is computerized by SoftWare House RobbiSoft Dec.90'/Jan.91'

What's in the CanDo HowTo Book?:

Chapter 1    What Does CanDO Do?                Page.

    CanDo Overwiew ................................................1-1

    Whatzinabox? ..................................................1-1

    CanDo System Requirements .....................................1-1

    You CanDo a Backup ............................................1-2

    CanDo on a Hard Disk or Floppy Disk ...........................1-2

    A couple of questions you might have ..........................1-3


Chapter 2    You CanDo It.

    Starting Cando ................................................2-1

    You CanDo an Application ......................................2-1

    Lets Do It ....................................................2-1

    First Project .................................................2-2

    Second Project ................................................2-9


                                      1

Chapter 3    Decks & Cards.

    Decks & Cards Overwiev ........................................3-1

    Menus .........................................................3-1

    Deck Menu .....................................................3-2

    Card Menu .....................................................3-2

    Mics. Menu ....................................................3-3

    Status Panel ..................................................3-3

    Edit Card .....................................................3-4

    Card Editor ...................................................3-5


Chapter 4    Objects.

    Objects Overwiev ..............................................4-1

    Buttons .......................................................4-5

    Windows .......................................................4-14

    Menus .........................................................4-20

    Fields ........................................................4-25

    Document ......................................................4-28

    Timers ........................................................4-32

    Sounds ........................................................4-34

    Animation .....................................................4-37

    Disk ..........................................................4-38

    Routines ......................................................4-38

    ARexx .........................................................4-39

    Xtras .........................................................4-40

                                      2

Chapter 5    Script Editor.

    Script Editor .................................................5-1

    Editor Tools ..................................................5-4

    Paint Editor Tool .............................................5-5

    Text Editor Tool ..............................................5-8

    Sound Editor Tool .............................................5-9

    Picture Editor Tool ...........................................5-10

    DOS Editor Tool ...............................................5-11

    File Editor Tool ..............................................5-11

    Coordinates Editor Tool .......................................5-11

    Card Finder Editor Tool .......................................5-12

    Routine Editor Tool ...........................................5-12

    Field Editor Tool .............................................5-13

    ARexx Editor Tool .............................................5-15

                                      3

Chapter 6    Commands.

    Commands Overwiev .............................................6-1

    Expressions ...................................................6-3

    Functions .....................................................6-10

    FlowControl Commands ..........................................6-18

    CardMovement Commands .........................................6-23

    Graphic Commands ..............................................6-24

    Screen and Window Commands ....................................6-35

    Brush Animation Commands ......................................6-38

    Audio Scripting Commands ......................................6-42

    Document Commands .............................................6-45

    File I/O Commands .............................................6-53

    Icon Commands .................................................6-55

    ARexx Commands ................................................6-58

    Object Commands ...............................................6-60

    Buffer Commands ...............................................6-62

    Mics. Commands ................................................6-66


                                      4

Chapter 7    Appendices.

    Commands Index ................................................7-1

    LoadFlags Appendix ............................................7-7

    Advanced Features .............................................7-8

    Error Messages - Syntax Errors ................................7-10

    Error Messages - Run Time Errors ..............................7-11

    Error Messages - File Errors ..................................7-13


                                      5

                                 Chapter 1

                            What Does CanDo Do?

    CanDo is a revolutionary, Amiga specific, interactive software
authoring system. Its unique purpose is to let you create real Amiga software
without any programming experience. CanDo is extremely friendly to you and
your Amiga. Its elegant design lets you take advantage of the Amiga's
sophisticated operating system without any technical knowledge. CanDo makes
it easy to use the things that other programs generate - pictures. sounds,
animations, and text files. In a minimal amount of time, you can make programs
that are specially suited to your needs. Equipped with CanDo, a paint program,
a sound digitizer, and a little bit of imagination, you can produce standalone
applications that rival commercial quality software. These applications may be
given to friends or sold for profit without the need for licenses or fees.
    Although CanDo is especially easy to use, it is extremely powerful
and versatile. Its uses range from building simple slide shows and interactive
presentations to animated multimedia productions, quality educational
software, and even sophisticated control applicatons that communicate with
external video and audio equipment. CanDo lets you build small programs and
add features as you need them.
    Since Cando opens the world of software development to all Amiga
users, is has the potential of making an endless number of applications
available to every Amiga owner. We are very excited about this becoming a
reality and hope to facilitate it with future enhancements and support.


Whatzindabox?

    Along with this Manual, the package should contain Two Disks:
CanDo and CanDoExtras. Also included in the box is a Registration Card that
you should take the time to fill out and return to us. This will enable us to
inform you of CanDo revisions and will help our technical support staff to
help you.
    Please take a look at the ReadMe files on each of the CanDo Disks.
They contain last minute information that was not available when this Manual
was printed. They may be viewed by doouble clicking their icons.


CanDo System Requirements

    CanDo will work on any Amiga computer that has at least on (1)
megabyte of memory. If you don't have a hard drive, it is recommended that you
have two 3 1/2" floppy drives. Since CanDo makes it easy to work with sizable
data like pictures and sounds, a hard drive and expanded memory will
dramatically increase your effciency and productivity. Be sure your Amiga is
running WorkBench version 1.2 or greater.
    This manual assumes you are familiar with the operation of your
computer as wxplanied in the manual that came with your Amiga. You should know
how to use the mouse, start applications from WorkBench, and do simple
WorkBench operatons.

                                     1-1

You CanDo a Backup

    Please, before you use CanDo, make copies of all the original disks.
Work with these copies and keep the originales in a safe place. For your
convenience CanDo is not copy protected so spread the word not the disk.

TO MAKE COPIES OF THE CANDO DISKS:

1. Write-protect both CanDo disks by flipping up the write protect tab on the
   disks. This will protect them from accidental erasure.

2. Place the CanDo disk into drive DF0: and select the disk icon so that it is
   highlighted.

3. Select Duplicate from the WorkBench menu. Select Continue when asked to
   insert CanDo.

4. Insert a blank disk into drive DF0: when asked for the disk.

5. Exchnage disks when requested and select Continue until the copy is
   complete.

6. Once you have a copy, rename it by highlighting the disk icon and selecting
   Rename from the WorkBench menu. Remove the "Copy of" text that was appended
   to CanDo. Be sure to delete any spaces that precede the name.

7. Repeat the procedure for the CanDoExtras disk.


CanDo on a Hard Disk or a Floppy Disk

CANDO ON A HARD DISK OR A FLOPPY DISK
    CanDo is easy to install on your hard disk. You'll need at least one
(1) megabyte free on your hard disk before copying CanDo and all the support
files.
    For floppy disk owners, CanDo will run directly from the working copy
you maed. You must start your Amiga with this CanDo disk and run CanDo from
the icon. You will likely choose to install CanDo on your own WorkBench
startup disk. This is done by using the CanDoInstall program found on the
CanDoExtras disk.

TO INSTALL CANDO ON YOUR WORKBENCH DISK OR YOUR HARD DISK:

1. Start your computer normaly andthen insert the CanDoExtras disk into drive.

2. Open the CandoExtras disk by double clicking its icon on WorkBench. Open
   the Utilities drawer.

3. Now the Installer program may be started by double clicking on its icon.

4. This program will guide you through the installation process for both
   floppy drives and hard drives.

5. Once the installation is complete, you may remove the CanDoExtras disk and
   close its window.

6. CanDo may mow be started from your floppy or hard disk by double clicking
   its icon.

                                     1-2

                   A couple of questions you might have...

WHY DO I NEED TO "INSTALL" CANDO?

    When CanDo is started, is looks in an Amiga system directory called
LIBS: and another called L: for support files. These particular directories
that the Amiga uses to keep special files. The CanDoInstall program copies
these files for you.

WHAT AM I CREATING WHEN I USE CANDO?

    The applications you create with CanDo are called Decks. This is
because they comprised of Cards. In CanDo you work with Cards one at a time
and they may have completely different environments and characteristics. When
you save a Deck from CanDo, it is like an executable program that you may
start by double clicking its icon on the WorkBench screen. These Decks are
actually small files that use a "Library" that is installed on your system.
All CanDo Decks and CanDo itself efficiently share the use of this library.
This arrangement enables you to run many Decks at the same time and use the
Amiga's memory and its resources to the full extent of its capabilites.
Remember, the CanDo library is not a distributable protion of CanDo.

HOW DO I MAKE A DISTRIBUTABLE CANDO APPLICATION?

    When you are ready to make an executable version of your program, you
can do so easily with the Binder. This utility can create a distritable
version of your project in either of two ways:

1. INDEPENDENT PROJECT: A form of your Deck whick will run on any Amiga,
regardless of whether or not CanDo is also available on the Amiga. Programs
produced in this way can be sold or distributed without a license or fees of
any kind. These programs have the primary part of the CanDo support software
built into them.

2. DEPENDENT PROJECT: A form in which the project will only run if you or your
friends, or potential customers, have CanDo already. This type of bound
project is significantly smaller in size than an Independent Project (it
shares the same library of functions that CanDo uses), and is the perfect way
to make a program which you intend to give or sell only to people who already
own CanDo.

                                     1-3

    To "Bind" a Deck, select the Deck's icon the you would like to make
standalone and then, while holding down the shift key, double click on the
Binder icon. It will guide you through the binding process and create a
standalone application. Remember the icon for your new application will not be
visible in a WorkBnech window until it is re-opened. The standalone deck may
now be distributed along with any graphics or sound files that it uses. Don't
forget that these resource files must be found in the directories that were
specified when the Deck was created.

CAN I MAKE ROOM ON MY CANDO DISK IF I DON'T NEED ALL THE FEATURES?

    CanDo is very modular in design. If you don't need some of its
features, you may remove them from your disk. If you don't use ARexx objects
you may open the Objects drawer and discard it. Similarly, you may discard
items in the EditorTools,Xtras, and HelpFiles drawers. Make sure you have a
backup of these files in case you need these features in the future.
    The modular design of CanDo also enables you to add features in the
future when they become available.

HOW DO I GET HELP?

    If you have a problem that this manual does not address, please call
our Support Staff at: [phone] or if you have a modem, you can call our
Product Support BBS at: [phone] (300/1200/2400 Baud)

                                     1-4

                                  Chapter 2

                                You CanDo It.

    There are two methods of starting CanDo.
FIRST: CanDo has a Workbench Icon. Double-clicking on this Icon automatically
       launches the program.
SECOND: CanDo may be launched from a CLI or Shell by typing

    CanDo

and then pressing RETURN. CanDo will begin to load. THE CANDO REPORTER, a
small message window, will appear and inform you that the files that makeup
CanDo and its user interface are loading. The last message you will see is
"All done, finishing up."
    Now, at the bottom of the display, you will see CanDo's MAIN CONTROL
PANEL and behind the panel is your default window.

You CanDo an Application.

    The first sorfware project that you're going to create is a very
simple one. When executed, this Program will open a Window, (or Card as we
will now call them). All CanDo applications consist of Cards and Decks. Cards
are the basis building blocks of any CanDo project. A Card contains a single
Window and all its Objects and Attributes. A Deck consists of several Cards.
Moing between Cards and Decks is a fundamental part og CanDo project design.
    We will begin working on the first Card of this three Card project.
It will have a full screen IFF Image displayed. On this Image, we are going to
place two Buttons (or Gadgets in Amiga-ese), one with the words "Next Critter"
written on it, and the other with the word "Quit". When the Button marked NEXT
CRITTER is clicked, a second IFF Image will be shown. Clicking it again shows
a thrid Image. Each Image is its own Card, with Buttons identical to the ones
on the other Cards that you have created. When any of the Buttons marked QUIT
are clicked, the program will stop and the user will be returned to the CLI or
Workbench.

Lets Do It.

    On the CanDo MAIN CONTROL PANEL there are three boxes: Status, Cards,
and Objects. There are two Buttons in the Status box: Design and Browse.
Selecting DESIGN allows you to create your projects. You can select BROWSE to
test or run your creations at any time, without exiting CanDo.
Ready to start?

                                     2-1

1.  Click on the DESIGN Button to begin working on your project.

2.  Click on the WINDOW Button (Pic.#1/Fig.#1) in the OBJECTS protion of the
    MAIN CONTROL PANEL. This is the first step in the creation of a background
    image for your first Card. You'll be shown the WINDOW EDITOR. This is how
    you'll describe your window. You can type your Window's name in the Field
    under "Window Title" but for this example, we want to clear out the default
    name.

3.  Click in the Field then press the RIGHT AMIGA KEY + X which will clear the
    Field. This will produce a blank Title Bar above your Window, giving it a
    cleaner look.

4.  Now click on the DIMENSION Button. The DIMENSION REQUESTER appears.
    (Pic.#1/Fig.#2)

5.  Click on the Button to the right of "Picture". This brings up CanDo's FILE
    REQUESTER. Use the requester to locate the file RABBIT.PIC that was
    incluced on your CanDoExtras disk. Refer to chapter 4-4 of the manual for
    information on how it operates.


6.  Choose the RABBIT.PIC file. The Path Field now showes the correct directory
    path and the File Field shoes "Rabbit.pic."

7.  Now click the OK Button. This will return you to the DIMENSION REQUESTER.
    The Button nest to "Picture" now shoes, the highlighted Name RABBIT.PIC,
    the File you chose. When your Window odes open it will have the proper
    dimensions and resolution for the picture file you have just chosen, with
    the picture as it's background.

                                     2-2

8.  Again click the OK Button. This returns you to the WINDOW EDITOR. On the
    right, you'll see several Buttons. You've already used the first one
    "Dimension". For this application, you'll also use the bottom one,
    "Options."

9.  Click on the OPTIONS Button. This will bring up the OPTIONS REQUESTER which
    has several choices. For this example, you will need to change only one of
    the default settings.

10. Click on the first Button, THE WINDOW HAS VISIBLE BORDERS. The Button will
    change to THE WINDOW'S BORDERS ARE INVISIBLE.

11. Now click on the OK Button. This will return you to the WINDOW EDITOR.
    (Pic.#1/Fig.#3)

12. Now click on OBJECTS. Thi brings up the OBJECTS REQUESTER. Click on the
    CLOSEBUTTON icon to deselect it, we won't need one. Click OK.

13. Click on the WINDOW EDITOR's OK Button. There's your Rabbit. You've
    created your Window and you are back at the CanDo MAIN CONTROL PANEL.
    To see the whole picture...

14. Click on the UP/DOWN ARROW Button on the right side of the panel. The
    panel will drop out of the way.

                                     2-3

15. Click the UP/DOWN ARROW Button again and the panel returns the to its
    working position. You're now ready to add a title to this picture. To
    do this you need to write a Script.

16. Click on the EDIT CARDS Button (Pic.#1/Fig.#4) in the Cards portion of the
    MAIN CONTROL PANEL. This will bring up the CARD SYSTEM. Here you will see
    a card Requester with one file name in it "Card#1". This is the Card
    you've been working on. Since it is already selected...

17. Click on the EDIT Button. This will bring up the CARD EDITOR. here you see
    three Button that allow you to attach Scripts to your Card. But what is a
    Script anyway?
    A script is a Command (or, more often, a series of them) to be
    executed under certain conditions in a CanDo project. A Script is often
    attached to an event in your application. In other words, events like
    clicking a Button, activating (clicking on) a Window, or goind from one
    Card to another can cause a Script of Commands to be executed. Script
    Commands can beused to play a sound or sound sequence, run animations,
    move from one Card in a Deck to another Card, add text to a Window and
    many mor complex tasks.
    While this example project uses scripts in their basic, most straight
    forward form, you may wish to take a moment to look at the complete list
    of Scripting Commands, together with descriptions, syntax, and examples,
    that appear in the Commands Section of this manual. This side trip will
    give you an idea of the power and simplicity of CanDo's Scripting
    Languarge.

                                     2-4

18. Now back at The CARD EDITOR, you will need to choose one of the three
    Buttons to add tie title to your picture. Your chices are: at the Card's
    StartUp. AfterStartUp, or when Leaving the Card. You want the title to
    appear in your Window immediately after the Rabbit graphic is displayed.
    Click the AFTERSTARTUP Button.
19. In the SCRIPT EDITOR (Pic.#2/Fig.#5), type the following lines verbatim.

    SETPAN 2
    PRINTTEXT "The Friends of Elly Mae",70,45

    The Setpen Command sets the color of the text to be written from the
    Window's palette. The PrntText Command simply prints the text within the
    quotes at the coordinates specified ( 70 , 45 ). This means 70 pixels over
    and 45 pixels down.

20. Click the OK Button to ad this Script to your project.

21. At the CARD EDITOR, click OK.

22. Now click EXIT to leave the CARD EDITING SYSTEM.
    You're back at the MAIN CONTROL PANEL. You may want to go into Browse mode
    to check your creation so far.

23. Click BROWSE in the STATUS PANEL.

    In the Cards portion of the MAIN CONTROL PANEL you see an Arrow
    (Pic.#1/Fig.#6) Button pointing to the right, that's the NextCard Button.
    When the NextCard Button is clicked, the next Card in your Deck in
    rendered (or "started-up") on Screen one after another. When you reach the
    last Card in your Deck and click NextCard again, CanDo loops back to the
    first Card in the Deck. Since we have only one Card so far in this
    example, clicking the NextCard Button will result in looping back to the
    same Card.

                                     2-5

24. Now click the NEXTCARD Button. Your Card, picture, title and all will be
    freshly rendered on your Screen. Not bad!.
    Now, we want to make this good lokking window do something else, so
    let's Add some Buttons.

25. First, click on the ADD Button in the OBJECT PANEL.

26. Then, click on the BUTTONS Button (Pic.#1/Fig#7) in the same panel. The
    BUTTON OBJECT SYSTEM REQUESTER will appear. This Requester asks you to
    locate the Origin Point of your new Button.

27. Click the OK Button.
    The EDIT BUTTON REQUESTER will be lowered revealing your full Screen. Move
    your Mouse to position the Pointer on Screen where you want your Button.
    For this execise move the Pointer to above the "T" in the word "The".

28. Now click and release the LEFT MOUSE Button to set the Origin Point. Move
    your Mouse, notice that it now controls the shape and size of a rectangle.
    Move the Mouse in any directon you choose, adjusting the rectangle until
    you are satisfied with its size and shape.
    If you don't like the Button for some reason, click the ESC Key and
    start the process over.

29. If the location and shape are to your liking, click the LEFT MOUSE Button.
    The BUTTON EDITOR REQUESTER will be displayed and the location (origin)
    coordinates of the Button you've just created, in horizontal and vertical
    format, will have been entered for you automatically. You will also see
    the Button shape you have created positioned on the Screen. You may edit
    these by clicking in the field and typing new coordinates. Edit "Horiz" to
    be 50 and "Vet" to be 25.
    There are three types of Buttons in CanDo: Area, Text, Image. The
    Button we're making will be a Text Button.

                                     2-6

30. Press the BOX next to "Text". This brings up the FONT/TEXT REQUESTER. Here
    you will select your Font. The default setting of Topaz 8 Plain will work
    well here.
    Notice, there are several style options available. This time choose
    SHADOWED.
    You'll also see three COLOR SELECTORS. Click the left one, it governs
    the color of the text on your Button.
    Across the bottom of the Screen you will see a Color Palette. Click
    on a bright, light color. Your choice will be displayed in the Selector
    you clicked on.
    You can also choose colors using the Arrows on the Selector. You may
    change the second Color Selector to suite your tastes. Try it.

31. Now, click in the "Text" Field and press the RIGHT AMIGA Key and X to
    clear the Field. Now type...

    QUIT

    This text will become part of the Button.

32. Click the OK Button. This will return you to the BUTTON EDITOR REQUESTER.
    To enable the "Quit" Button to actually end a project we must attach a
    Script to it. There are four Button Events which can trigger a Script.
    This time you want the Script executed when the Mouse Button is let up
    after being pressed. This is called a Release script.

33. Click on RELEASE in the Scripts portion of the Requester. A SCRIPT EDITOR
    REQUESTER will appear. Type:

    QUIT

34. Click on the OK Button.

35. At the EDIT BUTTON REQUESTER, click on the OK Button. Now you're back at
    the MAIN CONTROL PANEL.
    The procedure for making the second Button is exactly the same as the
    first except that this Button's text and positon will be different.

36. Click no ADD and then on the Button in the MAIN CONTROL PANEL. Place this
    Button's Origin to the right of the "Quit Button" you just created and
    draw another small rectangle. You may adjust its coordinates to a
    horizontal of 175 and a vertical 25. This time, the text for the button
    will be "Next Critter" and its Release Script will be:

    NEXTCARD

    When you have your new button finished you should click OK at all
    Requesters until you're back at CanDo's MAIN CONTROL PANEL.
    Now when you click "Next Critter" the project will go to its Next
    Card, which will also contain a Picture and some Buttons. What next Card
    you say? You can make on in less then thirty seconds.

                                     2-7

37. Click on the Edit Cards Button in the Cards portion in the main panel.
    This brings the CARD SYSTEM back up.
    Click on the DUPLICATE Button on the right of the Requester.
    A second Card will added to your project. This Card is a duplicate of your
    first Card. Since your first window was a Picture Window, the window in
    your second Card will be a Picture Window as well, complete with same
    graphics.
    The new window also has the same Window Options and Window Objects as
    the first window.
    The Buttons and scirpts are carried over to the new Card.

38. This window will require changes to the script, so, here at the CARD
    EDITOR, click on AFTERSTARTUP.
    When the SCRIPT EDITOR comes up, select the menu option CLEAR under
    the Scripts menu. Click YES to verify that you really want to du this.
    Then click OK to leave the SCRIPT EDITOR.
    Click Ok at the CARD EDITOR. Exit the Card Editing system. Your are
    now working on a new Card. And since we don't really want two pictures of
    the same rabbit, let's change the graphic to a different critter.

39. Click the WINDOWS Button on the MAIN CONTROL PANEL. In the WINDOW EDITOR,
    click on DIMENSIONS and then select PICTURE Button again to get the FILE
    REQUESTER.
    When it comes up, select the graphic file PORCUPINE.PIC. Click OK.
    Since the options of first window are carried over to this one, and we want
    to use them as they are, you cdan now click OK. Your second Card is now
    finished and operational.

40. The third and final Card will be by far the easiest to create. We are
    going to clone the second Card, complete with graphic, buttons, and
    scripts. Then, we'll simply substitute a new critter pic.

41. Repeat step 37 and there's no need to edit the AfterStartUp Script.

42. Repeat step 38 and this time use the MINK.PIC file. Return to the MAIN
    CONTROL PANEL. If you want, you can change the border style or text color
    of any button by clicking EDIT and then on the actual button you would like
    to edit.

43. If you're not at the MAIN CONTROL PANEL, return to it for your final step
    in this project. Under the "Deck Menu", select SAVE. You will be prompted
    to give a filename and pathname. Now click OK.
    And that's it! You've just created a working program. Congratulations.

                                     2-8

                                Second Project

    Your second Project will be very different from the first. It will be
an extremely useful and flexble Application, and in some ways, easier to
create the your first one was.
    We call this Application a "PowerPanel" and it puts almost any Amiga
Command or Application just a click of the Mouse away.
    You create it using CanDo's DOS Command. This Command allows you to
run any Program as though it was a CLI Command. Because all Programs cannot be
run through CLI, you should always consult the Program's Documentation before
using it with CanDo's DOS Command.

The PowerPanel.

    A PowerPanel is (or at least can be) a Window that opens on the
Worbench Screen with several Buttons on it. For example, there could be a
Button that says "Paint" on it. When the Button is clicked, the PowerPanel
could start your favorite paint program.
    These PowerPanel Buttons can set up entire environments: change
directories, make assignments... do almost anything.
    This PowerPanel example will be designed to perform functins
accessible to all Amiga / CanDo users:

    * Run CanDo

    * Run Phone Index ( a CanDo application )

    * Open a new CLI

    * Run the Workbench Calculator Utility.

    * Play some Sampled Sounds ( just for grins )
They're a breeze to create and run, so lets get started.

1.  Click the DESIGN Button.

2.  Click on the WINDOWS Button in OBJECTS. The WINDOW EDITOR REQUESTER will
    appear.

3.  Clear the "Window Title Field" and replace the title with... POWERPANEL

4.  Click on the DIMENSION Button. (Pic.#1/Fig.#2)

5.  The DIMENSION REQUESTER, appears. In the "Position and Size" portion set
    the Window's X coordinate to 50 and the Y coordinate to 15

                                     2-9

6.  Set the Window's Width to 177 and Hight to 78.

7.  You'll use four colors ( the Workbench colors ), so click on 4 under "# of
    Colors".

8.  Click OK to return to the WINDOW EDITOR REQUESTER.

9.  Click on the OBJECTS Button to open the OBJECT REQUESTER.(Pic.#1/Fig.#3)
    Here you see graphic representations of these familiar Amiga Window
    objects: Close Button, Depth Buttons, Drag Bar and Resizing Button. When
    added to CanDo Projects, all four Objects perform their standard
    functions.
    For example: a Window's Close Button will execute a Script when
    clicked which could quit the program, go to the next card, or perform any
    CanDo Command.
    For this Project select the CLOSE BUTTON, DEPTH BUTTON, and the DRAG
    BAR. When selected, their Buttons will be highlighted. Click OK to record
    these choices.

10. At the WINDOW EDIT REQUESTER. Click OK You are back at the MAIN CONTROL
    PANEL and a smaller Window has been opened on your Workbench Screen. This
    is your PowerPanel Window an you're ready to create your PowerButtons.
    First, we'll Add the Button that starts CanDo. It will be a Text
    Button and will be created in the same manner as the Quit Button in the
    First Tutorial Project. Only the placement of the Button on the PowerPanel
    Screen and the Text on the Button will be different.

11. Click ADD and the BUTTON Button under Objects.

12. At the Add New Button Requester click OK.

13. Move the Pointer to a position in the upper left corner of your PowerPanel
    Window. Click the LEFT MOUSE Button to set the Origin Point. Size the
    Button rectangle as before and click the LEFT MOUSE Button.

14. At the EDIT BUTTON REQUESTER in the Origin section adjust the Button's
    Origin Point by changing the Horizontal and Vertical coordinates to 13 and
    14. The exact size you made this Button is unimportant because it will
    automatically adjust to the size of the Text that we put in it.

                                     2-10

15. Now click on OUTLINE in the Border section.

16. At the BORDER SELECTOR click on the EMBOSSED Button. Now choose the Border
    Colors you want using the COLOR SELECTORE and click OK.

17. At the BUTTON EDIT REQUESTER click on the BOX next to "Text" under
    "Style". The TEXT BUTTON DEFINITION REQUESTER will appear. In this
    Requester you will set these parameters:

    Font:    TOPAZ
    Font Size:    8
    Font Style:    PLAIN
    Text Color:    ( Your Choice )
    Text:    CanDo

    With these settings click OK.

18. At the BUTTON EDITOR REQUESTER click the RELEASE Button under "Scripts".

19. At the SCRIPT EDITOR, the far right hand slider controls a List of Editor
    Tool Icons. Locate and the Select the DOS Editor Tool. (Pic.#1/Fig.#8)

20. At the CANDO FILE REQUESTER use the File List on the right to find, then
    Select the CANDO Program File. Click OK.

21. At the SCRIPT EDITOR you will see that the proper DOS Scripting Command
    has been automatically typed into the Editor. Click on OK.

22. At the EDIT BUTTON REQUESTER click OK. The MAIN CONTROL PANEL, your
    PowerPanel Window and it's first Button will appear.

                                     2-11

    The remainder of the Buttons you will define for this Project are
Text Buttons alson. Retrace steps 11 through 22 which you used to create your
first PowerButton but use these Button Definitions below. Other possible
differences can be variations in Font choice, Text Color and Border Style. Use
the DOS EDITOR TOOL to locate the program each button will start.

    Following is a description of each Button you need to define:

    Phone Index Button

    Button Co-ordinates:    72, 14
    Border Style:        EMBOSSED
    Font:            TOPAZ
    Font Size:        8
    Font Style:        PLAIN
    Text Color:        ( Your Choice )
    Text:            PHONE INDEX
    Program:            CanDoExtrax:Utilities/PhoneIndex


    Calculator Button

    Button Co-ordinates:    13, 32
    Button Style:        EMBOSSED
    Font:            TOPAZ
    Font Size:        8
    Font Style:        PLAIN
    Text Color:        ( Your Choice )
    Text:            CALCULATOR
    Program:            Sys:Utilities/Calculator


    New CLI Button

    Button Co-ordinates:    112, 32
    Button Style:        EMBOSSED
    Font:            TOPAZ
    Font Size:        8
    Font Style:        PLAIN
    Text Color:        ( Your Choice )
    Text:            NEWCLI
    Program:            C:NewCLI

                                     2-12

23. Return to the MAIN CONTROL PANEL. Now, let's add some text to the Window
    to explain that the Buttons at the bottom of the panel that we are about
    to add are for playing sounds. Click on the EDIT CARDS Button in the CARDS
    BOX. The CARD SYSTEM REQUESTER will appear. Press the EDIT Button to edit
    the only card listed, "Card#1" The CARD EDITOR REQUESTER will appear.
    Press the AFTERSTARTUP Button to add the Script that will be performed
    after the card's window has been opened and all the Buttons have been
    attached.

24. You want to print the text "Sound Samples" just below the Buttons you've
    already made. Type in the followind Script.

    SETPEN 1
    PRINTTEXT "Sound Samples",35,48
    PRINTTEXT

25. Press OK to save the Script. This will return you to the CARD EDITOR
    REQUESTER.

26. Press OK again to return to the CARD SYSTEM REQUESTER.

27. Now press EXIT to return to the MAIN CONTROL PANEL.

28. Click on BROWSE, and then click the NEXTCARD Button in the Cards panel.
    You'll see the text you just created appear in your Window.

29. Now click the DESIGN Button. You're going to add a few simple unmarked
    rectangular Buttons. Each one, when clicked, wil play a different sampled
    sound.

30. Click on EDIT and then on the BUTTONS Button in the Objects panel.

31. At the BUTTON EDITING SYSTEM, click ADD. When prompted, place the Origin
    of the first of these sound buttons in the lower left corner of your
    Window. This Button is going to be an "Area Button". When the EDIT BUTTON
    REQUESTER comes up, rename this Button "Sound1". Then, adjust the Button's
    co-ordinates to 13, 62.

32. Click on AREA and the AREA BUTTON REQUESTER will appear. Adjust the Button
    size to 25,10, using the Width and Height Fields in the Requester. All of
    our "Sound Buttons" will be this size.

33. Click OK to return to the EDIT BUTTON REQUESTER. The Border and High light
    styles may be experimented with, but the defaults will work well for your
    purpose. Now, you'll want to add a Release Script, so click RELEASE.

                                     2-13

34. At the SCRIPT EDITOR, click the SOUND EDITOR TOOL (Pic.#1/Fig.#9) on the
    right.

35. Select SET THE FILENAME from the PLAY A SOUND REQUESTER. This will bring
    up CanDo's FILE REQUESTER. Find the DOGBARK.SND file, select it and then
    click OK.

36. Click OK at the PLAY A SOUND REQUESTER. The PlaySound Command will have
    typed into your script. Click OK to save the script.

37. At the EDIT BUTTON REQUESTER. Click OK. You are now back at the MAIN
    CONTROL PANEL.

    There will be three more "sound buttons" like this one, except with
different co-ordinates and different sounds attached.

    REPEAT STEPS 29 THROUGH 36 USING THE BUTTON DEFINITIONS BELOW:


    SOUND 2

    Button Name:        Sound2
    Co-ordinates:        55, 62
    Area Button Size:    25, 10
    Sound file:        ( Your Choice )


    SOUND 3

    Button Name:        Sound3
    Co-ordinates:        97, 62
    Area Button Size:    25, 10
    Sound file:        ( Your Choice )


    SOUND 4

    Button Name:        Sound4
    Co-ordinates:        139, 62
    Area Button Size:    25, 10
    Sound file:        ( Your Choice )

    Save your Deck now. Under the Decks Menu Select "Save". Use CanDo's
File Requester to set the Path and File Name for your Deck. Click OK and
you're done.

                                     2-14

                                  Chapter 3

                                Decks & Cards

    A CanDo project is comprised of a Deck of Cards. CanDo Cards are
somewhat like Flash Cards in that only one is shown at a time. However, unlike
Flash Cards that only present information, CanDo Cards can both present and
receive information. Furthermore, you can make things "happen" on a CanDo
Card. You do this by making Objects.
    The Window Object allows you to specify the overall appearance of
your Card. Buttons and Menus, for example, allow the user of your project to
tell it to do something. Other Objects allow you to easily receive information
or otherwise control what is happening.
    By adding Objects to a Card, you design what it looks like and what
it does. The Card is simply a container for the Objects you give it. Some
applications only need a single Card, while others need many Cards to change
the interface, appearance or activity. By simply changing Cards, you can cause
dramatic or subtle differences in what is happening.
    When you have designed a Deck, you can save it to disk. This allows
you to later load that Deck back into CanDo for futher editing. The Deck can
be run separately by double clicking its icon from Workbench, or from a CLI
using the CanDoRunner program.

    When you are ready to make an executable version of your program you
can do so easily with the CanDo's Binder. It will create a new file that is a
runnable program. However, the program created by the Binder can not be
re-edited by CanDo. Make sure that you keep the original Deck saved by CanDo
for later editing.
    This Chapter tells you how to work with Decks and Cards. Chapter 4
describes the Objects you can add to a Card. Chapters 5 and 6 describe how to
write the Scripts that make your application come to life.


Menus

    When CanDo's Main Control Panel is the active window, you can access
CanDo's Menus. They are not accessible when hour application's Window is
active. By clicking on any portion of the Main Control Panel, not necessarily
on a Button, you activate the window. This gives you access to CanDo's Menus
when you press the right mouse Button.
    CanDo's Menus are: Deck, Card, Objects, and Misc. The Objects Menu is
described in Chapter 4.

                                     3-1

Deck Menu

The Deck Menu has five items: New, Open, Save, About, and Quit.

NEW

    New deletes all existing Cards and starts you up in the default
configuration. (see the Advanced Topics Appendix for changing the default
Deck.)

OPEN

    Open replaces the current Deck with on loaded from a file. CanDo's
File Requester allows you to locate the file. The file must be a Deck created
with CanDo. You cannot load a Deck that has been made into a stand-alone
program using CanDo's Binder.

SAVE

    Save writes the current Deck to a file specified with CanDo's File
Requester. A saved Deck can be loaded into CanDo using Open. It can also be
run separately by double clicking its Icon, or bound into a stand-alone
program using CanDo's Binder.

ABOUT

    About simply displays a little information about INOVAtronics and
CanDo.

QUIT

    Quit allows you to leave CanDo. A Requester will warn you if you have
modified the current Deck.


Card Menu

The Card Menu has five items: Goto, First, Last, Previous, and Next.

GOTO

    Goto... allows you to go to a specifiec Card. A requester will show
all the Card Names. Click on one of the names to highlight it. Clicking on the
Goto Button or double clicking one of the entries will cause you to change
Cards. When you want to stay on a Card, select the Exit Button.
FIRST

    First causes CanDo to go to the First Card in the Deck.

LAST

    Last causes CanDo to go the Last Card in the Deck.

PREVIOUS

    Previous causes CanDo to move back one Card. If you are on the First
Card, this will put you on the Last Card.

NEXT

    Next causes CanDo to move forward on Card. If you are on the Last
Card, this will put you on the First Card.

                                     3-2

Misc. Menu

The Misc. Menu has two items: SuperBrowse and System Info.

SUPERBROWSE

    SuperBrowse temporarily removes the CanDo interface to your
application. The MAIN CONTROL PANEL will disappear, and your application will
be able to interact a little faster. This mode allows you to see exactly how
your application will run as a separate program.
    When you enter SuperBrowse Mode, CanDo will open a small Window on
your Workbench Screen. When you double-click on the Window, CanDo's MAIN
CONTROL PANEL will reappear and you will no longer be in SuperBrowse Mode.

SYSTEM INFO

    System Info will display a requester displaying Available Memory,
CanDo version information, and other useful statistics.


Status Panel

    The Status Portion of the MAIN CONTROL PANEL (Pic.#2/Fig.#10) contains
the Browse and Design Buttons.

BROWSE

    By selecting BROWSE, you can test your application. Because CanDo is
monitoring your activity, your project will not be as responsive as when it is
running in SuperBrowse Mode or as a separate application.

DESIGN

    When DESIGN is selected, you can construct your application.
Selecting any Button on the MAIN CONTROL PANEL, other than Browse, will
automatically select Design.
    The FIRST, LAST, PREVIOUS, NEXT, and GOTO Buttons work the same as
their Menu counterparts.

                                     3-3

Edit Card

    Selecting the EDIT Card Button brings up the CARD LIST REQUESTER
(Pic.#3/Fig.#11). From this Requester you can Add, Edit, Delete, Duplicate and
Reorder Cards.


    This list on the left side of the CARD LIST REQUESTER contains the
names of all the Cards in the Deck. You can highlight a Card Name by clicking
on it in the list. The Buttons on the right side of the Requester will work
with the highlighted entry.

ADD

    The Add Button allows you to Add a new Card to the Deck. The New Card
will not contain any Objects. When you click this Button, the CARD EDITOR
REQUESTER will be displayed. This Requester is described later in the Chapter.

EDIT

    The Edit Button allows you to edit the currently highlighted Card. If
you double-click a CARD NAME, it will also edit the Card. In either case,
CanDo will go to the selected Card and display its CARD EDITOR REQUESTER.

DELETE

    The Delete Button deletes the highlighted Card. A Requester will ask
you if you really want to delete it. Be certain that you want to delete it.
The Card and all of its Objects are disposed of completely.

DUPLICATE

    The Duplicate Button makes a copy of the selected Card and Objects.
THE CARD EDITOR REQUESTER is then displayed for this Card. This allows you to
begin a new Card with a copy of the existing Objects.
    The list shows the Cards in the current order. The two large ARROW
Buttons allow you to reorder the Cards. By using these Buttons, you can move
the highlighted Card up and down through the list.

                                     3-4

Card Editor

    The CARD EDITOR REQUESTER (Pic.#3/Fig.#12) has a Field for the Card
Name and three Buttons for Scripts. You can change the Card Name by simply
changing the name in the field.
    The Card has three Scripts associated with it: Startup, AfterStartup,
and Leaving.

STARTUP

    The StartUp Script is performed before your Card's window opens and
before any other Objects on your Card are created. This is a good place from
which to initialize variables, load files, etc. Because the window has not yet
been opened, this Script cannot perform any sort of grphics commands.

AFTERSTARTUP

    In this Script, which is performed after your Card's window opens and
before (like Buttons) have been made, you may want to draw into your Card's
window, activate a particular text field, start a BrushAnimation or sound
playing, or perform other last-second steps before the user of your
application begins to interact with it.

LEAVING

    The Leaving Script is performed anytime you switch Cards. This Script
runs after your Card's Objects have been removed from the window. This is the
proper place to save any files that were changed on the Card that is ending,
before moving on to another Card or quitting entirely.
    NOTE: You cannot put any Card Movement Commands in the Leaving
Script.

                                     3-5

                                  Chapter 4

                                   Objects

    Lets start with some CanDo basics. Applicatons are comprised of a
Deck of Cards. You can have as many Cards in a Deck as you wish. Each Card in
the Deck has a Window. Like flash-cards, CanDo Cards are shown one at the
time.
    It's up to you how each Card looks. They can look similar to each
other or they can look completely diferent. CanDo gives you a lot of freedom
using the Amiga graphics and sounds.
    CanDo Objects, such as Buttons and Menus, are added to a Card
allowing you to interact with your application. Other Objects, like Timers,
allow you to set up events to control your application.
    The Objects on a Card make things happen in your application. The
Objects portion of the MAIN CONTROL PANEL (Pic.#3/Fig.#13) allows you to Add
and Edit the Objects.

                                     4-1

    While in DESIGN Mode, either the Add or Edit Button is highlighted.
This indicates the selected method of working with Objects. When ADD is
selected, clicking one of the Object's Button allows you to add an Object.
    Each Object has an EDITOR REQUESTER which alows you to define how the
Object appears and performs. While defining an Object, you give it a Name.
CanDo uses the Name to identify the object. Each Object on a Card must have
aunique Name. However, you can use the same Name for Objects on different
Cards.
    When EDIT is selected on the MAIN CONTROL PANEL, clicking on a
visible object (Buttons, Fields, Documents, Window Close Buttons or selecting
a Menu) brings up the EDITOR REQUESTER for the Object. Alternately, clicking
one of the Object Buttons in the Control Panel brings up an EDIT LIST
REQUESTER (Pic.#4/Fig.#14) displaying the Names, of the selected Object Type,
on the current Card. From this Requester you can Add, Edit, Delete, Duplicate
and Reorder Objects.

    The ADD Button works just as Add from the control panel. Selecting
the Add Button on the Control Panel is simply a shortcut to using the one on
this Requester.

    The EDIT Button allows you to edit the currently highlighted Object
in the list. Clicking this button brings up the EDITOR REQUESTER for the
Object Double clicking an entry automatically selects Edit.

    The DELETE Button deletes the highlighted Object. A REQUESTER will
ask you if you really want to delete the Object. Be certain that you want to
delete it. The Object is disposed of completely. It does not put it in the
Paste Buffer (see Object Menus).

    The DUPLICATE Button makes an exact copy of the selected Object. The
Object will be renamed in the same manner Workbench uses in duplicateing files
(ie. "copy of"). When you pres the Duplicate Button, the EDITOR REQUESTER will
be displayed with the copy of the Object. This allows you to easily create
similar Objects without starting from scratch each time.
    You can also Reorder the Objects. Visible objects, such as Buttons,
can beplaced on top one another. The list shows the order in which Cando adds
the Objects to the Card. Therefore, Objects that are lower in the list will
appear on top in the window. The MOVE OBJECT UP Button moves an object up in
the list and the MOVE OBJECT DOWN Button moves it down in the list.

                                     4-2

Object Scripts

    Objects make things happen bu performing Scripts. Each Object has at
least one Script that can be performed. Some can have more than one. The
Object's EDITOR REQUESTER contains either a button naming each Script or a
Scripts Button that will display the available Scripts. You can tell if a
Script already exists when the Button is black. Clicking the SCRIPTS Button
brings up the CanDo SCRIPT EDITOR.
Object Menus

    Clicking on any area of the MAIN CONTROL PANEL (it does not have to
be on a Button) allows you to access CanDo's menus using the Right Mouse
Button. Under the Objects Menus, you can select from Browse, Add, Edit, Copy,
and Paste. The Browse, Add, and Edit options perform in the same way as their
cooresponding Buttons on the MAIN CONTROL PANEL. The Menu equivalents provide
convenience in that the Amiga Shortcut Keys of AMIGA...B, AMIGA...A, and AMIGA
E can be used to select them.

    The remaining optins are Copy and Paste. These Options allow you to
Copy an Object into a Past Buffer, and to Paste it onto another Card.
    Selecting COPY allows you to copy an Object using two methods. First
you can click on a visible Object on your card. After doing so, the previous
Paste Buffer is replaced with the selected Object. Selecting one of your Menu
Item copies all Menu Items and Subitems from the selected Menu into the Paste
Buffer.

    For the second method, after selecting Copy from the Objects Meny,
you click on one of the Object Buttons in the Main Control Panel. This
displays the list of Object Buttons in the Main Control Panel. Double clicking
an Object name, or clicking the Copy Button puts the Object into the Paste
Buffer.

    Selecting PASTE from the Objects Menu adds the Object to the current
Card. When Paste is selected, the Object's EDITOR REQUESTER will be displayed.
You can then modify the Object before selecting OK, or select CANCEL to abort
the Paste operation.

                                     4-3

CanDo File Requester

    At various times, CanDo will display its FILE REQUESTER
(Pic.#4/Fig.#15) requiring you to specify the name and location of a file.
    A File specification has two parts: the Path and Filename. The Path
Field shows where the file is, and the File Field shows the name of the file.
    The smaller List on the left sets the Path. You can use it to locate
the Path using Drawers, Disks, Phusical Devices, and Assignments. By default,
the small list contains the list of Drawers or Sub-Directories in the
directory indicated by the Path. Clicking one of its entries, sets the Path to
the indicated directory.
    Clicking the DRAWER Button changes its name to Disks and the small
list will display the available Disk Volumes. Clicking the DISKS Button
changes it to Physical. The list now displays the available physical devices.
Not all of these can be used for accessing files! Clicking the PHYSICAL Button
changes it to Assign. Now the list shows the available assignments. (See your
Amiga documentation for setting these). Finally, clicking the ASSIGN Button
sets the list back to Drawer.
    Clicking the PARENT button changes the current Path to the parent
directory if there is one.
    The lager List on the right, allows you to select a File Name.
Clicking an entry puts the name in the File field. Double-clicking an entry
selects the name as though you clicked OK.
    Sometimes, the FILE REQUESTER will have an additional preview button
on it. For example: when you are suppose to find a picture file, there will be
an additional button SHOW IT!. Clicking it allows you to see the currently
selected file. When finding a sound file, the HEAR IT! Button allows you it
listen to it.
    Clicking OK selects the current file indicated in the Path and File
Fields. If the File needs to be a specific type, CanDo will verify it and
display an Error Requester when it is wrong.

    While using the various Requesters within CanDo, you have the option
of selecting Cancel or Ok. Ok accepts any changes you have made in the
Requester. Cancel causes CanDo to forget any changes. Selecting either Cancel
or Ok returns you to the previous Requester if there was one.

                                     4-4

                                   Buttons

    A Button is an area in a window that can be clicked with the Mouse
Pointer. When clicked, specified actions can be performed. CanDo allows an
unlimited number of Buttons ot be defined on the Screen.
    Selecting ADD in the OBJECTS PROTION OF THE MAIN CONTROL PANEL allows
Objects to be aded to your application. If you click the BUTTON Button on the
same panel the ADD NEW BUTTON REQUESTER will come up, direction you to locate
the Origin Point of the New Button with your Mouse. Now click the OK Button.
The ADD NEW BUTTON REQUESTE will be lowered revealing your full Screen. Next
move your Mouse, positioning th Pointer at a location on the Screen where you
want a Button. Now click the LEFT MOUSE Button to set the Origin Point. Your
Mouse now controls the shape and size of a rectangle representing a Button
area. Move the Mouse in any direction you choose, adjusting the rectangle
until you are satisfied with its size. If you don't like the Button for some
reason, press the ESC key and start over. If the Button is to your liking,
click the LEFT MOUSE Button again and The BUTTON EDITOR REQUESTER
(Pic.#5/Fig.#16) will be displayed.
    The BUTTON EDITOR REQUESTER allows you to edit the unique information
about each button. It displays the Button's Name, Origin, Button Style, Border
and Highlight Styles, and the avaiable Scripts. The origin coordinates of the
Button, in X (horizontal) and Y (vertical) format, will have been entered for
you automatically.

                                     4-5

Name

    The Name is a group of characters identifying the button. The same
name can not be used for more than on object on a card. The button isgiven a
default name "Unknown". However, you probably will want to name it something
that is meaningful to you. The Name can include any charcter. It has a maximum
length of 20 characters. When you press RETURN, CanDo will verify that the
name i unique.


Origin

    The Origin always indicates the location of the upper left corner of
a Button. The Horizontal value indicates the distance in pixels from the left
edge of the Window. The Vertical value indicates the number of pixels down
from the top of the Window. The present values can be changed by clicking in
these Fields and typing in new values with the keyboard.
    You can also set these values using the Mouse. First click the Origin
Button, and the ADD BUTTON REQUESTER will be lowered. Your Mouse now controls
the position of a recangle representing the Button Area. Now move the
rectangle where you want the Button to be. If, however you choose not to
change your present Button you can return to the BUTTON DEFINITION REQUESTER
by pressing the ESC key. When the new location looks good just click the LEFT
MOUSE Button and the BUTTON DEFINITION REQUESTER will reappear.

                                     4-6

Style

    CanDo has three Button styles: Area, Text and Image. When adding a
Button, a rectangular area is defined. This area represents the "Hit Area" for
an Area Button. Area Buttons do not have an image or text representing the Hit
Area. However, they can be placed over images in the Window.
    In addition to Area Buttons, CanDo allows you o use Text and Image
Buttons for representing Image and Irregularly Shaped Buttons. These Buttons
are described in greater detail in the Text and Image sections of this manual.
    The check mark in the BOX next to "Area" indicates the current Button
is an Area Button. Each Button style has a Requester containing unique
information for its particular requirements. Clicking the BOX next to the
indicated style, brings up the appropriate Requester and changes the Button
style. Clicking CANCEL, aborts this process.

    Clicking on the BOX next to "Area" brings up a requester cdontaining
information baout the size of the Area Button.
    This requester allows you to view or change the Width and Height of
the Area Button. These values can be changed using the Keyboard. However, they
can also be set using the RESIZE ON WINDOW Button (Pic.#2/Fig.#17). Clicking
on this Button lowers the MAIN CONTROL PANEL. Your Mouse is now controlling
the lower right corner of a rectangular box. The upper left corner is
stationary on the screen. This corner indicates the Origin of the Button. The
rectangular corner, and pressing the LEFT MOUSE Button a new area for the
button is defined. Pressing ESC, returns to the AREA BUTTON REQUESTOR without
modifying the Width and Height values (Pic.#4/Fig.#18).

                                     4-7

Border

    An Area or Text Button can have a Border around its Hits Area. There
are six Border Styles from which to choose. The default Border Style, Outline,
is shown in the BUTTON DEFINITION REQUESTER. By clicking on the BORDER Button
the BORDER SELECTOR (Pic.#5/Fig.#19), will be displayed.
    The BORDER SELECTOR displays the border styles from which to select.
The selected syle will have a Black Hit Area. Clicking the Hit Area of the
desired button selects the matching style.
    The bottom row contains a Cancel Button, two COLOR SELECTORS, and an
OK Button. The two Color Selectors change the colors used in rendering the
buttons border. The colors can be selected by using the two arrows on the
Color Selectors or by clicking one of the available colors at the bottom of
the Screen. The selected color is shown in the active Color Selector. Clicking
on one of the Color Selectors makes it active. The sample buttons on the
Border Selector depict the use of these colors.


Highlight

    When you click on a Button that you have made with CanDo, the Button
area can change to the existing color's Complementary color, or Outline the
area, or do neither. The default Highlight Style, Complement, is shown in the
ADD BUTTON REQUESTER. By clicking on the HIGHLIGHT Button the HIGHLIGHT
SELECTOR (Pic.#6/Fig.#20) will be shown.
    The three Highlight Styles: None, Outline, and Complement are shown
in this requester. Clicking on the associated button sets its Hit Area to
Black.

                                     4-8

Button Scripts

    There are four types of events that can occur by using a Mouse
Button. They are Click, Drag, Release, and Double Click. Each of these events
can have a Script associated with them. A script is simply a set of
instructions to perform.

CLICK

    Click events happen when the LEFT MOUSE Button is pressed while the
mouse pointer is over the Button. This type of event is useful for providing
immediate response to the mouse.

DRAG

    Drag events occur as the LEFT MOUSE Button is held down and moved
over the button's Hit Area. This is an uncommon type of button usage. However,
these movement events can be used for tracking mouse movements in applications
such as paint programs.

RELEASE


    Release events occur when the LEFT MOUSE Button is pressed and
released while over a button. This is the most common button application. By
delaying until the button is released, the user can decide to move the pointer
off the button, thus avioding an unwanted action.

DOUBLE-CLICK

    Double-Click events happen when the LEFT MOUSE Button is clicked
quickly two times. The Amiga Preferences allows a user to adjust the time
delay used in determining a Double-Click. This type of event is used to insure
that the user did not inadvertently press a button. The Icons on Workbench
work in this manner.

                                     4-9

Text Button

    Like an Area Button, a Text Button has a rectangular Hit Area.
However, CanDo will automatically display a text message in the hit area. You
specify the text massage, the font and point size, color, and style. The text
is simply characters that you want to represent the action performed by the
button. It can use any font avaiable in your "Fonts:" directury and can also
use a varity of Text Styles, to enhance its appearance. Like an Area Button, a
Text Button can have a Border around its Hit Area.
    An Area or Image Button can be changed to a Text Button by clicking
in the BOX next to "Text" in the BUTTON DEFINITION REQUESTER. You can change
the style of a Button as many times as you wish. When you have made your final
choice there is one important thing to remember about this process: each Style
has unique style information that must be saved. That information is saved
only when you click OK on the Buton Definition Requester.
    The TEXT BUTTON DEFINITION REQUESTER (Pic.#6/Fig.#21) is displayed
when the BOX next to "Text" is selected. A window on your screen displays the
appearance of the text message.
    The TEXT BUTTON DEFINITION REQUESTER allow you to select the font and
point size, the Text Style, the colors used, and the text message to use in
the button. Notice that you don't set the size of a text button. Its size is
determined automatically by the size of the message in the selected font.


Selecting a Font and Point Size

    The available fonts in your Fonts: directory are shown in a list. A
font can be selected bu clicking on its name with your mouse pointer. If you
have more fonts than can be displayed in the list, the slider allows you to
scroll through the list. The currently selected font is shown below the list.
The point sizes available for that font are shown in the list next to the
fonts. The selected size is shown below its list. When the font or size is
selected, the sample text will be updated to show its appearance.
    CanDo uses the current Fonts: directory. Some of you may have more
than one Font directory. With applications such as Paint programs, you can
change directories while working on a project. This is because the font is
only used while you are rendering text to the screen. Afterwards, it is not
needed anymore and you can change font directorires.

                                     4-10

    Because CanDo uses the selected font when displaying a button, all
fonts used by CanDo should be in the currently assigned Fonts: directory. If
you change the fonts in this directory, remember to run FixFonts before using
them. If the selected font can not be used, the system's default font will be
used.


Selecting Text Style

    The Amiga operation system supports Plain, Bold, Italic and Underline
text style. CanDo provides enhanced styles of Embossed, Outlined, Shadowed,
and Ghosted.


    Selecting Plain deselects all other Text Styles. Bold, Italic, and
Underline can be used with each other along with one of CanDo's enhanced
styles. Only one enhanced can be used at a time. The Sample text shows the
results of the selected styles.


Selecting Text Colors

    The TEXT SELECTOR has three COLOR SELECTORS. The first one is the
primary color. It is used with all styles for depicting the text. The other
two Color Selectors are used with the enhanced styles. The colors available in
the Color Selectors are the ones currently used in your screen. Different
color combinations provide different effects. Playing around with different
styles and colors will give you the feel of how to use them.


Selecting Text

    The Text defaults to the same name used for the button. However, it
doesn't have to be the same. The text can be changed using the keyboard.
Spaces at the beginning and the end of the text can be used to make the button
larger.
    Selecting CANCEL does one of two things. If the Button was previously
of a different Style the original Button Style will berestored. If it was
already a Text Button, any changes made will be forgotten. Selecting OK
accepts any change.

                                     4-11

Image Button

    Image Buttons have a small picture for a Hit Area. A "DPaint" style
Brush is needed to define the picture for an Image Button. Most paint packages
allow a portion of a oucture to be clipped and saved in a file. These small
pictures are called Brushes. CanDo allows a Brush to beused as an Image
Button. When a Brush is clipped from a picture, the back ground color is
transparent. While the Brush is rectangular, the Image appears to exclude this
one color. CanDo supports this technique in utilizing the Brush as a Button.
    While the background color is drawn, it is not included in the Hit
Area. This means that when the mouse is clicked on the background portion of
the image, the button is not activated. This allows irregular shapes, such as
arrows, to be used without including the area around the image as a Hit Area.
    An Image Button is created by clicking in the BOX next to "Image" in
the BUTTON DEFINITON REQUESTER. This will display the IMAGE BUTTON REQUESTER
(Pic.#6/Fig.#22).
    The IMAGE BUTTON REQUESTER allows you to select a "DPaint" style
brush file for the image. The Image Name Button indicates the Name of the
Brush File. By clicking the Button, you can locate the file using CanDo's FILE
REQUESTER.
    This Requester has a Button called "Show It!" The Show It Button
loads the Brush File and displays it in a Window on your Screen. This allows
you to see what the brush looks like. Don't be alarmed if a large brush is not
completely visible in the Window. The purpose of this feature is for you to
visually verify its appearance. If it is not a valid Brush File, CanDo will
display an Error message. If the Brush does not use the same display mode or
color palette as your screen, it might not appear as you expect. Keep in mind
that the Amiga can use only one display mode and one color palette on a single
screen. However, with some planning, you shouldn't have too much trouble
getting predictable results.

                                     4-12

    CanDo allows you to use the shape of a brush as the hit area, without
using it's image. Clicking the BOX next to "Use Shape Only" toggles this
feature. By selecting this feature, the non transparent colors in the brush
image define the hit area of the button. However, the image of the brush is
not rendered on the screen. This feature allows irrgularly shaped buttons to
be used without changing the image on the screen.
    As with the AREA and TEXT BUTTON DEFINITION REQUESTER, clicking
CANCEL aborts a style change or of any changes made in the IMAGE BUTTON
DEFINITION. Clicking OK accepts changes and returns to the BUTTON DEFINITION
REQUESTER.


Alternate Image Button

    An Image Button, that is not using the "Use Shape Only" feature, has
an additional Highlight option. Clicking on the BUTTON in the "Highlight"
section of the BUTTON DEFINITION REQUESTOR, displays the HIGHLIGHT SELECTOR
(Pic.#7/Fig.#23).
    However, this time the additional option, Alternate Image is
available. Clicking on this Buton displays CanDo's File Requester, allowing
you to locate the Brush File to use as the Alternate Image. The Show It Button
allows you to preview the Image. It is suggested that the Brush used for the
Alternate Image be of the same dimensions as the Brush used for the Image
Button. Otherwise, portions of an image will not be cleared when the image
changes.

                                     4-13

                                   Windows

    A Card always has a Window. The Window Object allows you to customize
each Card's Window. You can change the resolution, number of colors, or
provide a background image. You can also have close, resize and depth buttons.
Several other options allow you to tailor the appearance of the Window.
    Selecting the WINDOW object from the MAIN CONTROL PANEL, brings up
the WINDOW EDITOR REQUESTER (Pic.#7/Fig.#24).
    The Window Editor allows you to specify a Title for the Window. Along
the right side of the WINDOW EDITOR REQUESTER, are four Buttons: Dimension,
Window Colors, Objects, and Options. Each of these Buttons opens a Requester
allowing you to control specific aspects of the Window. The Window can have
four scripts associated with it: CloseButton, Resize, Deactivate, and
Activate.


Window Title

    This Field allows you to specify a Title for the Window Title Bar. If
the Window Title is empty, (you can do this easily by clicking in the Field
and pressing the AMIGA...X) no Title will appear. In addition, if you do not
specify a close button, depth buttons, and dragbar (see Window Objects) and
the Window Title is empty, the Window will not have a Title Bar.
    If you want to insure that you have a Title Bar, yet you don't want
to have a Title, put a space in the Window Title Field.

                                     4-14

Dimension

    Clicking the DIMENSION Button on the WINDOW EDITOR, brings up the
DIMENSION REQUESTER (Pic.#1/Fig.#2).
    The DIMENSION REQUESTER allows you to specify the Window size, and
number of colors. Alternatively, you can specify a Background Image. In
addition, you can specify an initial position.


Display Mode

    When providing the Width and Height, CanDo automatically determines
the Display Mode. The Amiga Display modes are Low-Resolution, Extra
Half-Bright, Hold and Modify (HAM), and High-Resolution.




    Widths up to 320 can be Low-Resolution, Extra Half-Bright, or HAM.
The  Display mode is determined by the number of colors. If you choose 32
colors or less you will be in Low-Resolution Mode. Choosing 64 colors produces
Extra Half-Bright Mode. Finally, 4096 colors gives you HAM Mode.
    Widths greater than 320 requires High-Resolution Mode and can have a
maximum of 16 colors. Interlace is usd with Heights greater than 200 (256 on
PAL Amigas). On the left side of the DIMENSION REQUESTER, four common screen
Sizes can be selected. Clicking on the appropriate Button sets the Width and
Height to the indicated values.


Position

    The X and Y values are the initial position of the Window. Most
application will use default values of 0 (Zero). If the Window has a dragbar
(see Window Objects), it can be repositoned with the mouse.
    The X value is only used when the Window is opened on Workbench (see
Window Options). It indicates the initial Horizontal position of the Window.
The Y value indicates the initial Vertical position. If the Window is opened
on Workbench, it will be used for the vertical position of the window.
Otherwise, it will be the initial vertical position of the new screen.

                                     4-15

Picture Window

    Clicking the PICTURE WINDOW Button brings up the CanDo's FILE
REQUESTER. The specified Image will be used as background image for the
Window. The Window's size and number of colors will be determined by the
picture. When a Picture Window has been selected, the Picture Window Button
will be highlighted. Changing the Width or Height values, or Number of Colors
will de-select the Picture Window.
    Clicking OK or CANCEL on the DIMENSION REQUESTER returns to the
WINDOW EDITOR.


Window Colors

    Clicking the WINDOW COLORS Button on the WINDOW EDITOR bring up the
COLOR REQUESTER (Pic#7/Fig.#26). It allows you to change the color used for
the Window's Background, Border and Text. These values can be set to the Color
number you want to use.

BACKGROUND COLOR
    The Background Color is the initial color of the Window. If you
specify a PICTURE WINDOW in the WINDOW DIMENSION REQEUSTER, this value will
not be used.

BORDER COLOR
    This is the color for drawing the Window's border and Title Bar. If
the Window does not have a border or Title Bar (see Window Options), this
value will not be used.

TEXT COLOR
    This color is used for the Window's Title. If the Window does not
have a Title Bar, it will not be used.
    Clicking OK or CANCEL will retur to the WINDOW EDITOR.

                                     4-16

Window Objects

    Clicking the OBJECTS BUTTON on the WINDOW EDITOR brings up the OBJECT
REQUESTER (Pic.#1/Fig.#3).
    This Requester allows you to specify optional Window Objects. There
are, from left to Right: Close Button, Depth Buttons, Dragbar, and Resize
Button. Click on the BUTTONS of your choice. The selected object will be added
to your Window.
    The Close Button object allow a Close Button script to be performed
when clicked. The Depth Buttons allow the Window to be pushed to the back or
brought to the front. The Dragbar allow the Window to be dragged. The Resize
Button allows the size of the Window to be adjusted. Note: If a Resize Script
exists, the Script is performed whenever the Window is resized.
    The Depth Buttons, Dragbar and Resize Button are most useful when
used with a Workbench Window. While they are not restricted to the Workbench
Window, they are used for working with more than one Window on a screen.
    Selecting OK or CANCEL return to the WINDOW EDITOR.


Window Options

    Clicking the OPTIONS Button on the WINDOW EDITOR, brings up the
WINDOW OPTIONS REQUESTER (Pic.#9/Fig.#28). This Requester allows you to select
various options effecting the Window. The default Options are shown below.

                                     4-17

    Clicking a Button changes the option. Each Buttons toggles between
two choices. The following image shows the alternative to the default Options
(Pic.#9/Fig.#29).

VISIBLE BORDERS
    The Window has an optional borde. When visible, a box is drawn around
the Window using the color specified in Window Colors. If the border is
invisible, the box is not drawn.

BACKDROP MODE
    A backdrop Window means the Window is attached to the screen. The
window will not have a Window Title and none of the Window Objects will be
attached. If this is a Workbench Window, the window cannot be positioned on
top of other windows nor can it be moved around. When the Window is opened on
a Custom Screen, you will have access to the Screen Title Bar allowing the
Screen to be lowered using the Mouse.

BRING WINDOW TO FRONT
    This option effects whether the window is visible when it is opened.
On a Workbench Window, the Window is allowed to be opened in front of, or
behind any Windows on the screen. On a Custom Window, it affects whether the
Screen is in front of or behind other Screens. You can use the WindowTo and
ScreenTo Commands to change the position of the Window or Screen.

                                     4-18

WINDOW ACTIVE
    The Amiga can only have one active window at a time. This Window
receives keyboard input, and its menus are available to be used. The Window
Activate option allows you to control whether your Window is the Active Window
when it is first opened. Most of the time you will want it to be Active.
However, you may wish to make a CanDo application that is started from a CLI
and has a Status Window on Workbench. If you want to be able to continue
typing in the CLI, without reactivating it, then you do not want your CanDo
Window to become Active.

WORKBENCH WINDOW
    This option tells CanDo to try to open the Window on Workbench. To do
so, the Window must use 2 or 4 colors. In addition, if your Workbench Screen
is non-interlace, the Window height can not be greater than 200 (256 on PAL
Amigas). If the Window can not be opened on Workbench, CanDo will open a new
screen.
    Clicking OK or CANCEL returns to the WINDOW EDITOR.


Window Scripts

    The Window has four scripts that can be performed. The CloseButton,
Resize, Deactivate, and Activate Scripts can be edited by clicking the
appropriate Button on the WINDOW EDITOR.



CLOSEBUTTON
    By enabling the CloseButton in Window Objects, the Window will have a
CloseButton in the upper left corner. This script is performed when the button
it is clicked on.

RESIZE
    When the Window is resized, you may need to redraw your Window.
Buttons, Fields, and Documents are redrawn automatically. However, all other
imagery is not. This script can contain commands to redraw the imagery in the
Window when it is resized.

DEACTIVATE
    When your Window is Active, and you click in any other Window, the
Deactivate Script is performed.

ACTIVATE
    When a user re-activates the Window this script is performed. The
Deactivate and Activate scripts can be used to pause an activity while the
another application is being used.

                                     4-19

                                    Menus

    CanDo allows you to create menus for your applications. Most likely
you're familiar with using the menus provided in most of the software on your
Amiga. CanDo lets you create Amia menus with the features you have become
accustomed to, and features such as Menu Images that even progessional
software seldom utilizes.


Features Provided in CanDo Menus

    * Multiple Menu Titles.
    * Menu Items and Subitems.
    * Shortcut keys.
    * Stylized Text Fonts.
    * Menu Images.
    * Alternate Text and Alternate Image Highlighting.

Menu Components

    Menu Titles are visible on the Title Bar of a window when the right
mouse button is pressed. They are text characters providing the context and
location of the available menus. CanDo allows you to have as many Menu Titles
as can be displayed on the Title Bar. When the Mouse Pointer is positioned
over a Menu Title with the RIGHT MOUSE Button pressed, its Menu Iterms become
visible.
    Each Menu Title will have at least one Menu Item. The Menu Items are
the selectable list of Text or Image entries associated with a Menu Title. A
Menu Item can have Menu SubItems. They become visible when the mouse is
positioned over the Meny Item. Like Menu Items, they can either be represented
by Text or an Image. Each Menu Item and Subitem can have a script that is
executed when it is selected. In addition, they can have a Shortcut key that
causes its script to be executed as though it had been selected using the
mouse.

                                     4-20

Adding and Changing Menus

    Menus are added and edited through Requesters. Unlike Buttons and
Fields, it makes no difference whether "Add" or "Edit" is selected in the
OBJECTS CONTROL PANEL. When the MENU Button is selected from the Objects
Control Panel, the MENU EDITING SELECTOR (Pic.#8/Fig.#30) is displayed.
    The MENU EDITING SELECTOR allows the creation, deletion, reordering,
and renaming of the Menu Titles. It also provides access to the Menu Items for
each Menu Title.
    If you have two or more Menu Titles, The Movement Arrows allow you to
chane their order. The top entry will appear at the far left side of the MENU
BAR. The bottom entry will appear on the right side.
    Selecting ADD or EDIT brings up the MENU TITLE EDITOR
(Pic.#8/Fig.#31). It contains the Menu Title. The Menu Title is the text that
appears on the Title Bar.
    When EDIT is selected the Menu Title Editor will contain the name of
the selected Menu Title. If you want to re-name it, simply change the name in
the Field.
    Selecting CANCEL returns to the MENU TITLES SELECTOR. Selecting OK
brings up the MENU ITEM EDITOR to the Menu Title.

                                     4-21

Menu Items

    The MENU ITEMS SELECTOR works in the same manner as the MENU TITLES
SELECTOR. Menu Items are created, deleted, reordered using this Selector. A
Menu Title must have at least one Menu Item. If you don't Add one before
selecting EXIT the Menu Title will not be created. Should you ever delete all
Menu Items from a Menu Title, the Title will be removed.
    Choosing EDIT or ADD brings up the MENU ITEM EDITOR REQUESTOR
(Pic.#10/Fig.#32). Add allows you to create a new Menu Item. Edit allows you to
change on existing one.
    The MENU ITEM EDITOR REQUESTER allows you to define and later modify
the features of a Menu Item. From this Requester, you specify the Object Name,
Highlighting Style, Meny Style, and a script to be performed when it is
selected. You can optionally define a Shortcut Key and menu Subitems.


Menu Item Name

    As with other Objects, the Object Name here provides a unique group
of characters identifying the Menu Item. It is the name that will be shown in
the MENU ITEMS SELECTOR for the Menu Title.


Menu Style

    Menu Items can be represented by an Image or Text. The check mark in
the BOX next to "Text" indicates it as the default style. Clicking on this BOX
brings up the MENU TEXT DEFINITION REQUESTER. It works the same way as the
TEXT BUTTON DEFINITION REQUESTER. The Text field defaults to the Menu Item
Name. However in can be altered to whatever you like.
    Clicking on the BOX next to "Image" brings up CanDo's File Requester.
It allows you to specify the "DPaint" style Brush you want to use as the Menu
Image. Clicking the SHOW IT Button will show you a representation of the Image
on your Screen. As with all brush images, it uses the Screens' resolution and
palette.

                                     4-22

Menu Highlight

    With the RIGHT MOUSE Button depressed and the Mouse Pointer
positioned over a Menu Item, it will be Highlighted. The Highlighting style is
indicated in the Button below "Highlight" in the MENU ITEM DEFINITON
REQUESTER. Clicking the HIGHLIGHT Button brings up the MENU HIGHLIGHTING
REQUESTER. This Requester allows you to select from the available styles.
    Both Text and Image items can have highlighting styles of None,
Outline, and Complement. The Default style is Complement. These styles work
the same way as their Button Object counterparts.



    Text Menus have the additional Highlight Style of Alternate Text.
Simply type the text into the field in the Alternate Text area of the
Highlight requestor. The Alternate Text uses the same font and style as the
Primary Text.
    Image Menus have the additional Highlight Style of Alternate Image.
Clicking on the ALTERNATE IMAGE Button brings up CanDo's FILE REQUESTER
allowing you to select a "DPaint" style brush file. While it is not necessary,
it is suggested that the brush be of the same dimensions as the first Image
used. If they are not, the image will not erase each other completely when
highlighted and un-highlighted or selected and released.


Selected Script

    A Menu Item has a single script that is performed when it is
selected. Clicking on the SELECTED Button in the Script area brings up the
CANDO EDITOR allowing you to edit the Script.
    The Menu Item is selected by pressing the RIGHT MOUSE Button and
positioning the Mouse Pointer over the Item then releasing the Button.


Shortcut Key

    CanDo allows you to assign a SHORTCUR Key to a menu item. All you
have to do is type a single character in the "Shortcut Key" Field. CanDo will
display the Shortcut Key symbol on the right side of the Menu Item. Pressing
the RIGHT AMIGA Button and the SPECIFIED Key, performs the Menu Item's
selected script as though it had been selected using the Mouse.

                                     4-23

Menu Sub-Items

    A Menu Item can have a group of selectable Menu Sub-Items. By
depressing the RIGHT MOUSE Button while the Mouse Pointer is positined over
the Menu Item, the Menu Sub-Items become visible. The Mouse Pointer can then
bepositioned over the Sub-Item you want. When the Right Mouse Button is
released, the Sub-Item is Selected.
    To Add or Edit an existing Menu Item's Sub-Items click on the BOX
next to "Sub-Item", This brings up the MENU SUB-ITEM SELECTOR. It works
identically to the MENU ITEM SELECTOR. Selecting ADD, brings up the MENU
SUB-ITEM EDITOR REQUESTER (Pic.#10/Fig.#33).
It allows you to define the Menu Sub-Item. This definition process is the same
as the MENU ITEM EDITOR REQUESTER. The only exception is that Menu Sub-Items
can not have additional Sub-Items. This is a restriction enforced by the Amiga
Operating System.
    After a menu Sub-Item is Added or Edited, clicking on OK will return
you to the MENU SUB-ITEM SELECTOR. Exiting the Menu Sub-Item Selector returns
to the MENU ITEM EDITOR REQUESTER.
    When a Menu Item has Menu Sub-Item, a check will appear in the Box
next to Sub-Items. If all Sub-Items are deleted, the check will be removed.
    One last thing to remember: when a Menu Item has Sub-Items, it can
not be selectd; only one its Sub-Items are selected. This means that the
Selected Script will not be performed when the mouse is released over the Menu
Item.

                                     4-24

                                    Fields

    A Field is an Area in which characters can be typed using the
keyboard. CanDo provides two types of fields, Text and Integer. Text Fields
allow any character, alphabetic or numeric to be entered, Integer Fields are
resticted to positive or negative numeric (integer) values.
    Click the ADD Button in the OBJECTS PANEL to tell CanDo you want to
add an Object. Next, click the FIELD Button, telling CanDo you want to add a
Field. When the MAIN CONTROL PANEL is lowered, position the Mouse Pointer
where you wnat the upper left corner of the Field. Click the LEFT MOUSE
Button. Now when you move the Mouse Pointer, CanDo will display a rectangular
box representing the Field you are creating. Now click the Mouse Button again.
The Screen will display the FIELD DEFINITION REQUESTER (Pic.#11/Fig.#34).
Pressing the ESC key before you define the field area, returns to the MAIN
CONTROL PANEL without adding a field.
    This requester contains the Field's Name, Origin, Width, Border
Style, Justification, Type, and the available Scripts. The Name, Origin, and
Border Style work the same as in the BUTTON REQUESTER.
    The Name is a unique identifier for this Object. The Origin values
can be altered directly with the keyboard or dynamically set using the Mouse
after clicking on the Origin Button. As with Buttons, you can set the Fields'
Border by clicking on the Text Button showing the current Border Style.
    The Font used within a Field is determined by a seting within your
preferences. Most likely, you have selected 80 column text. If so, the fields
will use Topaz 8. The characters in this Font have a height and with of 8
pixels. If you have 60 column text selected, the fields will use Topaz 9. Its
characters have a height of 9 and width of 10 pixels.


Field Width

    The Field's Width is shown in pixels. The number of displayable
characters is this width divided by the character width of your system font.
While it is not mandatory, it is best if the Field's Width is evenly divisible
by the font's width

EXAMPLE:
If your Field is 64 pixels wide, divide 64 by 8, (64/8) = 8

                                     4-25

    The Field's Width can be altered using Keyboard, or resized
dynamically on your screen using the Mouse. Clicking on the WIDTH Button,
lowers the CONTROL PANEL. The Mouse controls the width of a box representing
the Field. The left side of the box is fixed at the Origin. The right side is
adjusted with the Mouse. When the rectangle is the desired width, click the
LEFT MOUSE Button. If you don't want to resize the width, press the ESC key.


Type Alignment

    The information in a Field can be aligned Flush Left, Centered, or
Flush Right. The Default Alignment is Flush Left. This can be altered buy
clicking on the button in the Alignment Area.


Text Field

    The default Field type is Text. This is indicated by the check mark
in the BOX next to "Text". Clicking on this BOX brings up the TEXT FIELD
REQUESTER (Pic.#11/Fig.#35). It allows you to define the maximum number of
characters in a Field, and the INITIAL TEXT.
    The number of visible characters is determined by the field's width.
The Maximum Number Of Characters indicates the actual number of characters the
field can contain. If it is greater than the number of visible characters, the
contents will scroll as you type or use the arrow keys.
    The INITIAL TEXT allows you to specify the characters in the field
when is it created. However, a user can still alter the Field's contents.

                                     4-26

Integer Field

    From the FIELD DEFINITION REQUESTER, clicking in the BOX next to
"Integer" will bring up the INTEGER FIELD REQUESTER (Pic.#11/Fig.#36). It
allows you to specify the Maximum, Minimum, and Initial values for the Field.
    The INTEGER FIELD allows a user to type any valid integer. You can
automatically insure that the value is within a range by specifying the upper
and lower boundaries in the Maximum and Mimimum values.

EXAMPLE:
    If you set the Maximum Value to 1000 and the Minimum Value is 50, and
the user enters a value of 10, when he presses RETURN, the value is changed to
50, If you entered 1500, it would be changed to 1000.
    Using the Maximum and Mimimum values, Scripts can safely assume a
value is within the defined range. It also provides the user with immediate
feed back of the value being used.
    The INITIAL VALUE works similarly to the INITIAL TEXT. It provides a
default value for the Integer Field. This value can be changed by the user if
he so chooses.


Field Scripts

    Fields have two types of scripts, Selected and Return. The Selected
type of Script is executed when you click in the FIELD. The Return type of
Script occurs when the user presses the RETURN Key.

                                     4-27

                                   Document

    CanDo's Document Object allows you to choose between a Memo editor
and a List selector.
    The Memo editor is a multi-line text editor with optional scroll
bars. It provides for free form text input and display. The NO TYPING option
allows for a non-editable display.
    The List Selector displays a list of lines. The user of your
application can choose from this list by clicking with the mouse. File
Requestors use this technique to show a list of files.
    Both the Memo editor and the List selector use CanDo Documents. The
Document commands give you flexibility in the creation and manupulation of the
Document's text. These commands are described in the Scripting Commands
section.
    As with other Objects, the Name should be aunique name for an Object
for the Card. The Document field indicates the "Document name" to be used for
the Object. You should read more about "Document Name"'s in the Document
Scripting Commands. However, suffice it to say that this field indicates which
"Document Name" to associate with this Document Object. If the "Document Name"
has not already be created, CanDo will create a new one. When this is
necessary, CanDo will look for a file using the "Document Name" as the file
specification. If the file exists, it will automatically be loaded and
displayed in the Document Object. Otherwise, an empty document will be
created.

                                     4-28

Document Type

    The DOCUMENT EDITOR (Pic.#12/Fig.#37) allows you to choose between
Memo and List. A check mark indicates the current selection. When you click on
the BOX next to Memo, the MEMO FIELD OPTIONS REQUESTER (Pic.#12/Fig.#38) is
displayed.
    The MEMO OPTIONS REQUESTOR allows you to choose between the Scroll
Bar Options. It also allows you to select the No Typing option.
    Clicking the BOX next to No Typing enables and disables the option. A
check mark indicates that the user if your application can not type into the
Memo editor.

    The Memo Field Editor has four Scroll Bar Options from which to
choose. They are None, Horizonal Only, Vertical Only, and Horizonal &
Vertical. Clicking on the appropriate Image chooses the option. Clicking the
BOX next to List does not display a Requester.


Document Definition

    Four Buttons along the right side of the DOCUMENT EDITOR REQUESTER
allow you to define the Origin, Size, Font, and Border for the Document
Object.

                                     4-29

Document Origin

    Clicking the ORIGIN Button brings up the DOCUMENT ORIGIN REQUESTER
(Pic.#12/Fig.#39).
    The Horizontal and Vertical Fields allow you to specify the location
of the Document. The Horizontal Field indicates the number of pixels from the
left edge of the window. The Vertical Field indicates the number of pixels
down from the top of the window. You can reposition the document by clicking
the Button SET ORIGIN ON SCREEN. Your mouse will move a rectangular box the
size of your document. Position the box and click the mouse, or press ESC to
abort. The Horizontal and Vertical Fields will be updated to the origin
position.


Document Size

    Clicking the SIZE Button displays the DOCUMENT SIZE REQUESTER
(Pic.#12/Fig.#40).
    The Width and Height Fields allow you to specify the document's
dimensions. These Fields show the current values. You can modify them
directly. In addition, clicking the Button SET SIZE ON SCREEN allows you to
dynamically set them using the Mouse. The Mouse controls the corner opposite
the origin point. Adjust the size of the box and click the mouse to set the
values or press ESC to abort.

                                     4-30

Document Font

    Clicking the FONT Button displays the DOCUMENT FONT REQUESTER
(Pic.#6/Fig.#21).
    The DOCUMENT FONT REQUESTER allows you to choose the Font and point
size for the text to be displayed in the Document. You can also choose between
Plain and a combination of Bold, Italic, and Underlined Text. Finally, you can
choose the colors used for the text. The COLOR SELECTOR on the left is for the
Text and the one on the right is for the background.


Document Border

    Clicking the Border button displays the same Border Requester used
for buttons.


Document Scripts

    The Document Obejcts use the same Scripts as Buttons: Click, Drag,
Release, and Double. They work in the same manner. When the user first presses
the Left Mouse Button, the Click Script is performed. While thet hold the
Mouse Button down and move the pointer over the document, the Drag Script is
performed. When they Release the Mouse Button, the Release Script is
performed. And finally, if they Double Click on the document, the Double Click
Script is performed.

                                     4-31

                                    Timers

    CanDo has two types of timers: Interval and Alarm. Interval Timers go
off after alength of time has elapsed. Alarm Timers go off at a specified time
of day. When a Time goes off, the Occrred Script is performed.
    The TIMER EDITOR REQUESTER has two forms. Someof the titles and
buttons are changed when selecting between Interval and Alarm Timer. Interval
is the default setting. It is indicated by the check mark next to "Interval".
    An Interval Timer can go off once after the elapsed time or it can be
Reoccurring. This causes it to occur repetitively after the each interval. A
Reoccurring Interval Timer, with a short elapsed time, can cause seemingly
continuous activity while allowing other Object's Scripts to be performed if
necessary.
    When Interval is specified, the TIMER EDITOR REQUESTER
(Pic.#13/Fig.#42) allows you to specify the time interval and whether or not the
timer is re-occurring.
    The time interval is specified in Minutes, Seconds, and Jiffys.
Jiffys are fractions of a second. On NTSC Amigas, the U.S. standard, Jiffys
are 1/60th of a second. On PAL Amigas, Jiffys are 1/50th of a second. The
values can be set directly using the keyboard, or moditied using the increment
/ decrement Buttons next to each field.
    Clicking the BOX next to "Reoccurring", causes the Interval Timer to
repeat continuously. For example: If the interval is set to 2 seconds,
00:02:00, the Occurred script will be performed every 2 seconds. Clicking the
BOX next to "Reoccurring" toggles it On and Off. A check in the box indicates
that it's on.

                                     4-32

    Clicking the BOX next to "Alarm" indicates the Timer should go off at
a specified time. The ALARM TIMER can be set to occur every day or on a
specific day of the week (Pic.#13/Fig.#43).
    The Hour, Minute, and Second Fields let you indicate the Time for the
Alarm. These times can be set using the keyboard, or they can be set using the
Buttons next to each Field. The Alarm's Day Segment can be set by clicking the
Buttons AM or PM which toggle between the two.
    Alarm Timers can be set for every day or for a specific day of the
week. The default setting is Every Day. By clicking the DAY OF THE WEEK
Button, it cycles through each day of the week and Every Day.

                                     4-33

                                    Sounds

    The CanDo Sound Object allows you to synchronize other sounds and
graphics with a sound. The Sound Object does NOT play the sound. It simply
allow you to perform scripts when a specified sound starts or finishes
playing. While it does not play the sound, it does load it into memory, if it
is not already loaded there. When adding or editing a Sound Object, CanDo will
display the SOUND EDITOR REQUESTER (Pic.#14/Fig.#44).
    Clicking the BUTTON next to "Sound To Wait For" brings up CanDo's
FILE REQUESTER allowing you to locate the sound associated with this object.
If must be a valid 8SVX sound. 8SVX is the IFF sound standard supported by the
Amiga.
    Also on the FILE REQUESTER, you can press the HEAR IT! Button to
preview the sound. After pressing OK, the SOUND EDITOR REQUESTER will reappear
and display the name portion in the "Sound To Wait For" Button.
    The Sound Object waits for the specified sound to begin or finish
playing. Any script on the current card can play the sound using the PlaySound
or PlaySoundSequence Commands. However, they must use the exact same file
specification as the "Sound Name". If the same sound is played using a
different file specificaton or "Sound Name", the Sound Object's scripts will
not be performed.


Scripts

    A sound is played using the PlaySound and PlaySoundSequence Commands
(see the Sound Editor Tool and Sound Commands). Whenever the specified sounds
begins to play, the Start of Sound script is performed. When the sound is
completed, the End of Sound script is performed.

                                     4-34

                                  Animation

    CanDo allows you to display DPaint III style BrushAnims. The
Animation Object does NOT display the BrushAnim. It simply allows you to
perform scripts at specific points in the animation. This lets you coordinate
other activities with the animation. Selecting the Animation Button form the
Main Control Panl, brings up the BrushAnim Editor Requester (Pic.#14/Fig.#45).
    An Animation Object works with a single BrushAnim. The Animation
Object's Scripts are triggered by the specified BrushAnim's activities. If you
want Scripts associated with two BrushAnims, then you need to make two
Animation Object's. Clicking on the FILENAME Button brings up CanDo's File
Requester allowing you to locate a DPaint III style Brush Animation. Clicking
the SHOW IT! Button allows you to preview the animation.


Scripts

    The Scripts for the specified BrushAnim can never be performed unless
it is being displayed. The ShowBrushAnim Command can be performed in any
Script except for a Card's StartUp Script. If you want it to be shown when you
to a Card you should put it the AfterStartUp Script. See BrushAnim Scripting
Commands for more details.
    The Animation Objects allows you to perform a Script on each frame of
an animatin, on specific frames, or when a moving BrushAnim reaches a
Destination.

                                     4-35

Every Frame

    This Script is performed before each frame of the animation is shown.
Depending on how long you make this Script, the animation may be slowed down
drematically.


Destination

    This Script is performed when the animation reaches the destination
of a MoveBrushAnim or MoveBrushAnimTo Command.


BrushAnim
Frames...

    Individual Scripts can be performed before specific frames are shown.
THE LIST REQUESTER shows the frame numbers for which there is a Script. The
Buttons on the right hand side allow you to Add, Edit, and Delete Scripts from
the list. Clicking ADD displays the BRUSHANIM FRAME REQUESTER (Pic.#12/Fig.#46).
    It has a Slider allowing you to quickly choose the Frame Number. The
selected Frame is shown in the Frame Field. You can also enter the Frame
directly into the Field. If you click OK, the CANDO SCRIPT EDITOR will be
displayed. When you finish creating the Script, the BRUSH ANIM EDITOR will be
re-displayed.

                                     4-36

                                     Disk

    CanDo provides a way of performing a Script when a diskette is
removed from or inserted into the disk drive. This can be a fun way of playing
different sounds when disks are removed and inserted. While it is not usually
necessary, your application can monitor the available volumes. The Disk Object
provides a way of performing these tasks (Pic.#15/Fig.#47).
    The Disk Object has two Scripts. Disk Removed and Disk Inserted. The
scripts are performed whenever a diskette is removed or inserted from any
drive.

                                     4-37

                                   Routines

    Routines allow you to write a Script that can be performed by any
Object. When creating the Routine, you give it a Name. The Script is performed
using the Do Command with this name (see documentation on the Do Command for
more details).
    Unlike other Objects, the Routines Object is global to all Cards.
This means that a Routine is accessible from every Card in your Deck.
    Routines keep you from having identical Scripts in different Objects.
When you want multiple Objects to do the same thing, simply put the common
scripting commands in a Routine. You can then access the Routine from any
Object's Script using the Do Command.
    The ROUTINE EDITOR (Pic.#16/Fig.#48) has a field for the Routine's
Name. The Do Command uses this Name to access the Script. When using the Do
Command, put the Name in double "the name" qoutes.
    The Script Button allows you to write the Routine's Script. The
Script can contain Do Commands. While it is valid for a Routine to Do itself,
you should not try this unless you are familiar with the advanced programming
techniques. It is very easy to create an endless loop that uses all remaining
memory.

                                     4-38

                                    ARexx

    Your application can listen to one ARexx port at a time. This port is
specified using the ListenTo Command (see ARexx Commands for more
information). Other Applications can send messages to this port. Amessage is
simply an ASCII string. The first word of the message is the Command Word.
When a message is received, CanDo uses the Command Word to see if you have
ARexx Object that corresponds to it. If there is one, its Occurred Script is
performed. Clicking the AREXX Button on the MAIN CONTROL PANEL, brings up the
AREXX EDITOR REQUESTER (Pic.#16/Fig.#49).
    The Object's Name Field is initially empty. If you do not fill it in,
it will automatically be set to the word you put in Message Field when you
press the OK Button.
    The Message Field should contain a single word indentifying the
message's Command Word. When a message is received, and its Command Word
matches the word you put in this Field, the Occurred Script is performed. The
script can then use the System Variable TheMessage which contains the complete
text of the message just received.
    By making a series of ARexx objects, one for each Command Word that
can be performed by your application, you can very easily create a complete
ARexx server.

                                     4-39

                                    Xtras

    This Objects portion of the MAIN CONTROL PANEL contains the core
group of Objects supported by CanDo. As more Objects are added, they will be
accessible through the Xtra's Button.
    In addition to Objects, the Xtras give you access to expanded
operations. These Operations can also beaccessed through the Xtra's Button.


    Each CanDo Xtra has a file in the Xtra directory. As additional Xtras
become available, you simply put its file in the Xtras directory. Because the
Xtra Objects and operations are not individually documented in this manual,
there will be documentation files on the disk.
    Pressing the XTRA Button on the MAIN CONTROL PANEL brings up the XTRA
SELECTOR (Pic.#16/Fig.#50).
    This Selector contains a list of the available Xtras. Simply DOUBLE
CLICK an entry or click the PERFORM Button. When you do so, the selected
operation will be performed. You should make sure you are familiar with what
the Xtra is going to do by reading its documentation.

                                     4-40

                                  Chapter 5

                                Script Editor

    Every Object has at least one Script that can be performed. By
clicking a button on the Object's Editor Requester, you can edit the Script
using CanDo's Script Editor. The Script contains Commands telling CanDo what
you want to happen when the Script is performed. CanDo's Scripting Commands
are described in Chapter 6.
    This Chapter describes how to use the Script Editor and Editor Tools.


Menus

    The Script Editor works like most text editors. Using the keyboard
and cursor keys you can type in your script. The vertical Slider on the right
lets you scroll through a script.
    The Editor has four Menus: Script, Text, Edit, and Misc. Some of
their Menu Items have SHORTCUT Keys. These Menu functions can be invoked using
the RIGHT AMIGA Key.


Script Menu

    The Script Menu contains: OK, CANCEL, VERIFY, CLEAR, and PRINT.

OK

    OK verifies the script and returns to the CanDo requester from which
you invoked the Script Editor. If the script contains an Syntax Error, a
requester will indicate nature of the error. When you select Continue, the
cursor will be placed af the beginning of the problem line.

CANCEL

    Cancel returns to the previous requester without including any
changes made to the script.

VERIFY

    Verify checks the syntax of the scirpt. Although this is done
automatically when you select OK, this option allows you to verify the script
without leaving the Scripting Editor. If an error is detected, a requester
will indicate the error and your cursor will be move to the beginning of the
line containing the error.

CLEAR

    Clear erases all lines in the Script Editor. Should you inadvertently
clear a script, select Cancel and re-invoke the Script Editor.

PRINT

    Print sends the entire contents of the Script Editor to the Printer.

                                     5-1

Text Menu

    The Text Menu allows you to Load, Save, and Insert text.

LOAD

    Load replaces the contents of the Script Editor with the contents of
a Fil. Cando's File Requester allows you to locate the file.

SAVE

    Save writes the contents of the Script Editor to with CanDo's File
Requester, and inserts it into the Script at the currently exists, it will be
replaced.

INSERT

    Insert takes the contents of a file, specified with CanDo's File
Requester, and inserts it into the Script at the current cursor position.
Unlike Load, it does not first clear the existing script.


Edit Menu

    The Edit Menu allows you to Search For and Replace text in the
Script.

SEARCH

    Search... searches for the next occurrence of a text string. A
requester allows you to specify the string to search for.

SEARCH NEXT

    Search Next searches for next occurrence of the last text string
specified with Search...

REPLACE

    Replace... searches for the next occrrence of a text string and
repleaces it with another. A requester allows you to specify the Search string
and the Replace String.

REPLACE NEXT

    Replace Next repeats the last Replace... operation without bringing
ip the Search/Replce Requester.

REPLACE ALL

    Replace All replaces all occurrences of a text string with another.


Misc. Menu

    The Mics. Menu contains: Help, Delete Line, Delete to EOL, and
Undelete Line.

HELP

    Help brings up the Scripting Help Requester. This Requester is
described later in this Chapter.
DELETE LINE.

    Delete Line erases the current line. It can be restored using
Undelete Line.

DELETE TO EOL

    Delete to EOL erases all characters from the current cursor position
to the end of the line. The characters can be restored using Undelete Line.

UNDELETE LINE

    Undelete Line restores the characters erased by the last Delete Line
and Delete To EOL.

                                     5-2

Shortcut Buttons

    Six of the Menu Items have a shortcut button located at the top of
the Scripting Editor: OK, Cancel, Search..., ...Next, Replace..., and Help.
These buttons work the same way as their menu counterparts.

Scripting Help

    You can get help on CanDo's Scripting Commands, Functions and System
Variables through the SCRIPTING HELP REQUESTER (Pic.#15/Fig.#52). If is invoked
by selecting the Help Menu Item under Misc., by clicking the HELP button, or
double clicking a word in your script. CanDo will try to give you help for the
word under the cursor or for the first word on the line.
    The main area of the requester displays the help message. When there
is more information than can be displayed in the message area, you can use the
NEXT PAGE Button to move forward. The PREV PAGE Button can then allow you to
move backwards.
    Some of the words in the message area can be clicked on for
additional help. You can identify these words because they will be in Red. By
clicking on a RED WORD, a related help topic will be shown i place of the one
which you are currently reviewing. When you want to return to the previous
help topic, press the BACK Button. If you have moved several levels from your
original Help Message, you can return to the first one by pressing the TOP
Button.
    The Topics, Commands, Functions, and Variables Buttons allow you to
look up other Help Messages. By pressing one of these Buttons, the list on the
right will contain a selection to choose from.
    Pressing the TOPICS Button displays a list of Topics such as Graphics
and Card Movement. When you select one of the listed Topics, the lister will
the display all of the Commands for the Topic and the COMMANDS Button will be
highlighted. Clicking on one of the Entries in the list, displays its Help
Message.
    By clicking the FUNCTIONS Button, the list will display the Functions
for the Topic. Clicking the VARIABLES Button shows the System Variables.
    When you are ready to return to the Script Editor, press the Exit
Button.

                                     5-3

                                 Editor Tools

    Along the right side of the Script Editor is a selection of Editor
Tools. These Tools allow you to interactively create scripts.
    For beginners, this is an easy way to get started without spending
too much time learning Scripting Commands. In fact, using the Editor Tools can
be the easiest way to learn. By using them to create your own "examples", you
can learn both specific Commands and the way CanDo's Scripting Commands work
in general.
    Advanced Users can create a "rough" script performing some of the
tasks they want to accomplish. By changing a few constants to variables, and
adding a loop, or other such modifications, it can be very easy to create
sophisticated scripts.
    Some Tools make it easy to access things that CanDo "knows" about.
Card, Routine, and File Names, to name a few, are more easily and accurately
identified using Editor Tools. Other Tools simply let you see the results
before you try it out.
    When you click on one of the Icons, a specialized requester will help
you in creating your script. Feel free to just play around with the Tools.
However, you should be familiar with CanDo's ARexx capabilities befoe
exploring the ARexx Editor Tool.

                                     5-4

                              Paint Editor Tool

    The Paint Editor Tool works like a small paint program. By using its
Tools, you can draw in the window and it will create the necessary Scripting
Commands. By selecting the PAINT EDITOR TOOL ICON (Pic.#18/Fig.#53), CanDo will
display the EDITOR TOOL PANEL. At the very bottom a color bar will display the
current color palette. The Paint Editor Tool is designed to look and feel like
a simple painting package. You simply select a drawing Tool, a color to use,
and draw in your window.
    While it may seem like a paint program, you need to be aware that you
are creating a Script. Each action you take generates Scripting Commands. It
is very easy to create large Scripts using this Tool.

                                     5-5

Dots and Continuous dots and Drawing Lines

    These Tools allow you to draw in a series of dots or small connected
lines. Simply select a color and draw using the LEFT MOUSE Button. You should
keep in mind that these Tools can easily create large Scripts.
    The Line Tool allows you to draw a line in the window. Simply
position the mouse pointer, press and hold the LEFT MOUSE Button, move the
mouse pointer and release the Mouse Button. A line will be draw between the
two points.

Flood Fill

    The Flood Fill Tool allows you to fill an enclosed area with the
selected color. Position the mouse pointer on your window and click the LEFT
MOUSE Button.

Triangle and Area Triangle

    These Tools allow you to draw triangles. The Triangle Tool draws with
lines, and the Area Triangle Tool draws filled Triangles. Simply define one
side of the triangle in the same manner as drawing a line. When you release
the mouse button, the pointer will control the position of the third vertex.
Position the pointer and click the LEFT MOUSE Button.

Parallelogram and Area Parallelogram

    These Tools allow you to draw parallelograms, a four sided polygon
with parallel lines. The Parallelogram Tool draws with lines, and the Area
Parallelogram Tool draws with a solid color. Draw a line by positioning the
mouse pointer at the first vertex, press and hold the LEFT MOUSE Button, and
drag the mouse pointer to the second vertex and release the Mouse Button. The
Mouse pointer will now control the three remaining sides. As you move the
pointer, a parallelogram will be formed. When you press the Mouse Button
again, the final image will be displayed.

Rectangle and Area Rectangle

    These Tools allow you to draw a rectangle with lines or a filled
block. Position the Mouse pointer, press and hold the LEFT MOUSE Button to
define on of the corners. While holding down the Mouse Button, drag the
pointer to the opposite corner and release the Mouse Button.

Circle and Area Circle

    Using these Tools, you can draw filled or unfilled circles. These
Tools do not automatically adjust the radius for all screen dimensions.
However, you can use the ellipse Tool for these situations.
    Position the Mouse Pointer then press and hold the LEFT MOUSE Button.
This defines the cente of the ellipse. While holding the mouse button, drag
the pointer to define the size of the circle and release the Mouse Button.

Ellipse and Area Ellipse

    These Tools allow you to draw filled or unfilled ellipses using the
currently selected color. Position the Mouse Pointer and press the LEFT MOUSE
Button. This defines the center of the ellipse. While holding the Mouse
Button down, drag the pointer to define the size and shape of the ellipse and
release the Mouse Button.

Brush Clip

    This Tool copies a rectangular area of the current window so it can
be used be the Draw With Brush Tool. Simply positon the Mouse Pointer to one
of the corners and press the LEFT MOUSE Button. While holding down the left
mouse button, drag the pointer to the opposite corner and release the mouse
button. The Draw With Brush Tool will automatically be selected.

                                     5-6

Draw with Brush

    This Tool draws with a clipped brush created using the Brush Clip
Tool. CanDo will not allow you to select this Tool if you have not previously
clipped a brush. When this Tool is selected, you will see the clipped image as
you move the mouse pointer. Simply position the image and click the LEFT MOUSE
Button.

Draw-Mode

    The Draw-Mode Button toggles between Normal and Complement
(Pic.#17/Fig.#54).
    While in Normal Mode, the drawing Tools will draw using the currently
selected color. While in Complement Mode, the drawing Tolls will completement
the colors over which they are drawing. The advantage of Complement Mode is
that when the script is repeated, the drawing will Complement back to what is
was.

Multi-Mode

    The Multi-Mode Button toggles on and off. When it is off, drawing
Tools will draw a singe image. When it is on, the Line, Triangle,
Parallelogram, Rectangle, Circle, and Ellipse Tools will draw multiple images.

Clear

    The Clear Button clears the window. Remember, this plaecs a
ClearWindow Command in the Script, and is not the same thing as starting over.

Undo

    The Undo Button will undo previous operatons. Each time you press the
Undo Button, the last operaton will be forgotten, and all remaining operations
will be re-displayed, This can be repeated until all operations have been
forgotten. This provides the unique feature of unlimited undo's. However, you
need to keep in mind that you are removing Scripting Commands.

                                     5-7

Selecting a Color

    The COLOR SELECTOR (Pic.#17/Fig.#55) displays the current drawing
color. You can use the up and down arrows to step through the available color,
or simply click on the color in the COLOR BAR. The PALETTE SLIDERS allow you
to change a color.
    Remember, changing a color generates a Scripting Command. It does not
change the initial Palette. Rather, it changes the color when this Script is
performed. NOTE: You should avoid changing the colors in a Workbench window.


                               Text Editor Tool

    The Text Editor Tool helps you print text in your window. When you
select the TEXT EDITOR TOOL ICON, the TEXT EDITOR TOOL REQUESTER will be
displayed.
    Selecting the SET TEXT AND FONT... Button brings up the TEXT AND FONT
REQUESTER (Pic.#16/Fig.#56).
    This requester works in an identical fashion to the TEXT BUTTON
DEFINITON REQUESTER described on Page 4-10.
    After setting the Text and Font, click the SET POSITION... Button.
This will allow you to position a representation of the text using the mouse.
Click the LEFT MOUSE Button when it is positioned where you want it to be.

                                     5-8

                              Sound Editor Tool

    The Sound Editor Tool helps you play sounds. CanDo supports the
playing of 8SVX digitized sound files, the standard supported by the Amiga.
This Tool helps you select a sound, volume and audio channel.
    Selecting the SOUND EDITOR TOOL ICON brings up the SOUND EDITOR TOOL
REQUESTER (Pic.#16/Fig.#57).
    This Requester allows you to choose from three options: selecting a
sound file, changing the volume, and selecting an audio channel. You can
choose one or more of these options. CanDo will produce the Scripting Commands
for the options you choose. For example, you can select a sound File and a
channel and not choose a volume.
    Clicking the SET THE FILENAME... Button brings up CanDo's FILE
REQUESTER. You can use it to locate the sound you want to play. When you
select OK, CanDo verifies the File is an 8SVX digitized sound, and returns you
to the SOUND EDITOR TOOL REQUESTER.
    Selecting the SET THE VOLUME... Button brings up the SET VOLUME
REQUESTER (Pic.#15/Fig.#58).
    This Requester has slider and a field you can use for selecting the
volume level. The slider is scaled from 0% to 100%. As you move the slider,
the value in the Volume Field will show the equivalent volume setting. This
value ranges from 0 to 64. You can also set this value using the keyboard.
When you select OK, the SOUND EDITOR TOOL REQUESTER is re-displayed.
    NOTE: When you change the volume setting, all subsequent sounds will
be played at the selected volume.

                                     5-9

    Selecting the SET THE CHANNEL... Button from the SOUND EDITOR TOOL
REQUESTER brings up the SET CHANNEL REQUESTE (Pic.#17/Fig.#59).
    This Requester allows you to specify a specific audio channel on
which to play a sound. If you do not select a channel, the sound will play on
the next available sound channel. By chosing a specific audio channel, you can
control which speaker the sound is played on. Audio channels 0 and 3 are
played on the left side, and channel 1 and 2 is played on the right side.

However, if the specified audio channel is being used when the Script is
performed, the sound will nut be played.
    When you select one of the four Buttons, it will become highlighted.
When you select OK from the SET CHANNEL REQUESTER, you will return to the
SOUND EDITOR TOOL REQUESTER.
    Remember, whatever you are using the SOUND EDITOR TOOL REQUESTER, you
can select OK and CanDo will return you to the SCRIPT EDITOR. CanDo will
produce the Scripting Commands for the options you have selected up to that
point.


                             Picture Editor Tool

    The Picture Editor Tool helps you locate a Picture and creates the
Command to show it. When you select the PICTURE EDITOR TOOL ICON, CanDo's FILE
REQUESTER will allow you to find the picture file. When you select OK, CanDo
will create the Command to show the picture.

                                     5-10

                               DOS Editor Tool

    The DOS Editor Tool helps you Run another program. When you select
the DOS Editor Tool Icon, CanDo's File Requester will appear. Locate the
program you want to run, and press OK. CanDo will verify it is an executeable
program.
    This Tool creates a DOS Command. It simply tells the Amiga Operating
System to execute the program within the quotes. The Editor Tool puts the word
"c:Run" in front of the program you selected.

FOR EXAMPLE:

    DOS "C:RUN C:DIR"

    This allows your CanDo application to continue running after is
starts the selected program. If you want your CanDo application to wait until
the selected program is done, you can remove the word "C:RUN" from the
command.

    DOS "C:DIR"

    Some programs allow parameters to be passed on the command line. You
can do this by adding them after the selected program.

    DOS "C:DIR >RAM:WORKFILE"

    This final example would execute the Dir command in the C: directory.
It does not have a "RUN". Therefore, your CanDo application will wait until
the command has completed before continuing. Finally, it tells the Dir command
to save its output in a file called "RAM:WORKFILE".


                               File Editor Tool

    The File Editor Tool helps you to locate a file using CanDo's File
Requester. It does not create a complete Scripting Command. It simply returns
the file specification enclosed in double qoutes. Many of CanDo's Commands use
a file specification in this form. This way, you can use the File Editor Tool
to locate the file for one of these Commands.


                             Coords. Editor Tool

    The Coordinates Editor Tool allows you to find the x,y coordinates of
a location on your Window. When you select the Coordinates Editor Tool Icon,
you should move the cross-hairs to the location you want and press the Left
Mouse Button.
    This Editor Tool does not create a complete Scripting Command. It
simply returns the horizontal and vertical values for a single location. Many
of CanDo's Scripting Commands use these x,y values. You can use this Editor
Tool for finding x,y coordinates for one of these Commands.

                                     5-11

                               Card Finder Tool

    The Card FINDER EDITOR TOOL helps you with Card Movement Commands.
Selecting its Icon displays the CARD FINDER REQUESTER (Pic.#19/Fig.#60).
    This Requester has Buttons on the left side for each of the options,
and a list of all Card Names on the right side. This list works in conjunction
with the first two options, inserting the Card Name and inserting a "Goto". By
clicking on one of the entries, the Name is placed in the Card Name Field.
    After selecting a Card Name, pressing the INSERT THE NAME OF THIS
CARD Button returns you to the Editor. The selected Name will be typed into
your Script.
    Selecting one of the four Buttons at the bottom, FIRST, PREVIOUS,
NEXT, and LAST, inserts a single Scripting Command. These Commands do not use
the selected Card Name.


                             Routine Editor Tool

    The Routine Editor Tool displays a list all the Routine names and
allows you to insert the Name or a "Do" Command for the Routine. When you
select the ROUTINE EDITOR TOOL ICON, CanDo will display the ROUTINE FINDER
REQUESTER (Pic.#17/Fig.#61).
    The ROUTINE FINDER REQUESTER displays a list of all currently defined
Routines in a list on the right side of the Requester. By clicking on one of
the entries, its Name will be placed in the Routine Name Field.
    When you select the INSERT THE NAME OF THIS ROUTINE Button, CanDo
will put the Routine Name, enclosed in quotes, into your Script.
    When you select the INSERT A "DO" TO THIS ROUTINE Button, CanDo will
put a Do Command into your Script.

                                     5-12

                              Field Editor Tool

    The Field Editor Tool helps you with the Field Object. The Field
Object allows the user of your application to enter or otherwise edit a single
line of text or an integer number. You can set or retrieve the contents of a
Field using Scripting Commands. This Editor Tool assists you in doing this.
    Selecting the Field Editor Tool Icon displays the FIELD EDITOR TOOL
REQUESTER (Pic.#19/Fig.#62).
    This Requester displays the Object Name for all Fields on the current
card and gives you three Scripting options. You can simply insert the Object's
Name, set the contents of the Field, or retrieve the contents of the Field.

Selecting a Name

    Each Field is given a Name on the FIELD EDITOR REQUESTER. The Names
for all Field Objects are displayed in the list on the right side of the FIELD
EDITOR TOOL REQUESTER (Pic.#19/Fig.#62). By clicking an entry, the Name will
be put into the FIELD NAME Field. You should select an entry by clicking one
of the three Scripting options.

Insert Field's Name

    Clicking the INSERT THE NAME OF THIS FIELD Button automatically types
the selected Object Name with double qoutes on each side. This is a simple way
of finding a Field Name and using it with a Scripting Command. This option
does not produce a complete Scripting Command.

                                     5-13

Set Field's Contents

    Clicking the SET THIS FIELD'S CONTENTS TO... Button displays the SET
FIELD REQUESTER (Pic.#17/Fig.#63).
    The New Value Field allows you to type in a value to be put in the
selected Field. If the selected Field is an Integer Field, you will be limited
to entering a valid integer value. Otherwise, you can enter any characters you
wish. Remember, if you want to include any double qoutes, you should put two
in a row (""). Selecting OK creates the necessary Scripting Command and
returns you to the Editor.

Put in a Fields Contents

    Selecting the PUT THIS FIELD'S CONTENTS INTO... Button displays the
GET FIELD REQUESTER (Pic.#19/Fig.#64).
    This Requester aids you in retrieving the contents of a Field and
putting the value into a variable. You need to provide the Variable Name on
the provided Field. Clicking OK creates the necessary Scripting Command and
returns you to the Field Editor Tool.

                                     5-14

                              ARexx Editor Tool

    The ARex Editor Tool helps you send and receive ARexx messages. If
you are interested in doing this, it si recommended that you read both the
ARexx Object and ARexx Commands sections before doing so. While this Editor
Tool makes it easier to produce the ARexx Commands, you should first
familiarize yourself with the ARexx concepts.
    Before sending ARexx messages to an application, acquaint yourself
with its ARexx capabilities. It should have documentation for its ARexx Port
Name and the Commands it can receive.
    After selecting the AREXX EDITOR TOOL ICON, CanDo will display the
AREXX EDITOR TOOL REQUESTER (Pic.#20/Fig.#65).
    From this Requester you can select a Message Port to listen to or
speak to, or send an ARexx Message to the current SpeakToPort.

ListenTo

    Selecting the SELECT A MESSAGE PORT TO LISTEN TO... Button, displays
the LISTENTO REQUESTER (Pic.#20/Fig.#66).
    This Requester allows you to specify the ARexx Port Name that your
application uses to receive ARexx messages. It is recommended that you put
this in the StartUp Script of your first Card. Selecting the INSERT THE
"LISTENTO" Button inserts the Command and returns you to the Editor.

                                     5-15

SpeakTo

    Selecting the SELECT A MESSAGE PORT TO SPEAK TO... Button from the
AREXX EDITOR TOOL REQUESTER displays the SPEAKTO SELECTOR (Pic.#20/Fig.#67).
    The SPEAKTO SELECTOR displays all of the Public Message Ports. While
an ARexx Port is Public, not all Public Ports can receive ARexx messages. In
fact, sending a message to some ports will cause the Amiga to crash. You
should know the Name of the Port to which you wish to send a message. This
Selector simply makes it easier for you to find the Name and insure that it is
currently available.
    Clicking an entry selects the Name and puts it into the Port Field.
Selecting the INSERT THE "SPEAKTO" Button or double clicking an entry inserts
the Command and returns to the Editor.

Send Message

    Selecting the SEND AN AREXX MESSAGE Button from the AREXX EDITOR TOOL
REQUESTER displays the SEND AREXX MESSAGE REQUESTER (Pic.#21/Fig.#68).
    This requester allows you to send a message to the current
SpeakToPort. Simply enter the message and click the INSERT THE "MESSAGE"
Button. This will insert the SendMessage Command and return you to the Editor.

                                     5-16

                                  Chapter 6

                                   Commands

    CanDo has over 200 scripting Commands and Functions. However, you
shouldn't feel as though you need to know how to use all of them in order to
make your application. In fact, you really only need to know a few to get
started.
    You should use the Editor Tools to get your feet wet. By looking at
the Commands they produce, you can learn a great deal about the way the
Commands work.
    At first you will want to use this Chapter as a reference for the
Commands your encounter. As your needs grow, you will want to read about a
certain cleasses of Commands. This Chapter is organized for this purpose. Each
section describes certain aspects or classes of Commands.
    While you do not initially have to understand Expressions and
Functions, you should eventually read the first two sections of this Chapte.
By making use of Expressions and Functions, you can easily add a lot of
sophistication to a simple application.
    The FlowControl and CardMovement Commands are very powerful. They
allow you to change what is happening in your application. The CardMovement
Commands, in particualr, are very simple and you should learn to use them
early on.
    The Graphic, Screen and Window, Animation, and Audio Commands are the
spice you use in your CanDo applications. However, these comprise the majority
of the Commands and they amy take little while to master. Keep in mind that
you don't have to learn to use everything. If something seems complicated,
come back to it later.
    The Document Commands are unique. You can use them with the Document
Objects or for internal manipulation of text. These Commands bring an
additional level of power to the manipulation text. Depending on your needs,
you may not want to work with these initially.
    File I/O, Icons, ARexx, Object and Buffer Commands should be
considered advanced. Power users can use these Commands to make applicatons
that rival professional software.
    Finally, Mics. Commands rounds off a few Commands that you may find
useful in your application.

                                     6-1

Command Symbols

    There are several symbols used in describing the various Commands and
Functions.

    < > are used to indicate Integers. *
    " " are used for Stings. *
    « » are used for Logicals. *
    { } are used to show optional parameters are Optional.
    ,   a Comma separates parameters.
    ;   end of a Command line.

    KEYWORDS are always shown in all capital letters.

    * You should read the Expression System sectoin for an explanation of
      Integers, Strings and Logicals.

                                     6-2

                                 Expressions

    An expression is a group of constants, variables, and functions
combined with operators. You use expressions to tell CanDo's scripting
commands what to do.
    Most of the time, you will use constans such as 5,"Hello", and ON.
However, sometimes you will want to do more sophisticated operations.
Expressions allow you to describe a value that is determined at the time the
command is performed.
    Cando's expression system has been designed to be as intuitive as
possible. Numbers are represented as integer constants. Strings are contained
in double "quotes". And logical values use names such as ON, OFF, YES, NO,
TRUE, and FALSE. In addition, you can mix integer, string, and logical values
within expressions, and CanDo will automatically convert the values as needed.
    This section describes the details of CanDo's expression system.
While it is not necessary for you to understand all aspects of this system,
CanDo provides many sophisticated operations and functions. Depending upon
your experience level, you may want to use this as a reference section or you
may want to read it for a complete understanding of CanDo's expression system.
Either way, you should at least scan it to get a grasp of its principles and
abilities.
    Most of CanDo's scripting commands use expressions to provide the
information for the operaton. For example, the LET command saves a value in a
variable. The format for LET command is:

LET VariableName = expression.

The results from evalution the expression is saved in the indicated variable.

Example:
    LET X = 100

    In this example, 100 is a simple expression containing a single
integer constant. It is saved in the variable 'X'.

    LET Y = X * -2

    The expression in this example is 'X * -2'. The result, -200, is
assigned to the variable 'Y'.

    LET Z = 5 + ABSOLUTE ( Y + 10 )

    This expression uses the ABSOLUTE function. A function takes one or
more parameters within parenthsis, performs an operation, and returns a single
value. Each parameter within a function can be an expression. The parameter
for the ABSOLUTE function, in this example, is the expresson 'Y + 10'. As you
might expect, the ABSOLUTE function returns the absolute value of an
expression. The absolute value of the expression '-200 + 10' is 190. 'Z' is
assigned the value of '5 + 190', or 195.

                                     6-3

    An Expression is a combination of constants, variables, and functions
with operators for computation. The evaluation of an expression results in a
singel value.
    Within CanDo, expressions use three types of values: Integer, Strings
and Logicals.


Integers

    Integers are the basic numeric system for dealing with graphics and
computer control. Integers are whole numbers that range from -214.783.648 to
214.783.648.
    An integer constant is a series of digits. A minus sign preceding the
digits indicates a negative integer. A plus sign is not necessary to indicate
a positive integer. However, it can be used to provide clarity.

Examples:
    105    -5000    +6


Strings

    Strings are groups of characters. String constants are characters
contained within double quotes. For example: "Fred is Here". However, the
double quotes are not part of the string. They simply show where the string
begins and ends.
    Strings can be as large as available memory will allow. Or a string
can be empty. An empty string is often referred to as a null string. CanDo
recognizes a null string as two double quote marks "".
    Strings can contain any character. These include many that are not
visible or are considered part of the International characte set.
    For a string to contain a double quote, it must be typed twice within
the string. CanDo will teat is as though only one is contained in the string.
For example "Fred says""Hi"" th everyone." contains the word "Hi" within the
string.


Logicals

    Logicals (known as Booleans) simply mean true of false. The words
TRUE and FALSE are logical constants. Within CanDo, YES and ON also mean TRUE.
Similarly, NO and OFF mean FALSE.


Variables

    A variable is a name to be used in the place of an integer, string,
or logical constant value. Variables can be thought of as storage locations
for values. CanDo does not require you to 'declare' a variable.
    Variable names may contain letters, digits, and underscore character
(_). The name must begin with a letter. The names can be any length. However,
longer names use more memory and take longer to identify.
    Any variable name can be used for integers, strings, or logicals.

                                     6-4

LET

LET VariableName = expression

    The LET command allows you to save a value in a variable. CanDo
evaluates the expression and then saves the value in the variable. This value
will be used in the evaluation of expressions containing the variable.
    CanDo also provides system variables and functions such as 'MouseX'
and 'Sign (expr)'. With the exception of these variables and functions, any
variable name can be used.


Expressions

    An expression contains constants, variables, and functions that can
be combined with operators to form a new value.
    An example of a simple expression is 'Count + 5'. The first value,
'Count', is a variable. The second value, '5' is an integer constant. The '+'
represents the addition operator. This expression adds the constants of the
variable 'Count' with 5.
    Constants, variables, and functions can be used interchangebly as
values within an expression.
    An operator is a symbol that represents a process to be performed on
one or two values.
    CanDo allow any type of value to be used with any operator. Strings,
integers, and logicals can be used interchangeably with any operation. Each is
automatically converted to the type of data used by the operator.

Examples:

"-1000" + 5

    The additon operator (+) adds two integer values. The first value,
"-1000" is a string. It is automatically converted to an integer value of
-1000 and is added to 5. The result of this expression is -995.


"-1000" || 5
    The string concatenation operator (||) appends two strings together.
The first value in the expression is a string "-1000". However, the second
value is an integer constant 5. It is converted to a string constant of "5"
and appended to "-1000" the result of this expression is "-10005".

    The default value for an unassigned variable is either an integer
ZERO (0), a string NULL ("") or a logical FALSE. The default value used is
determined by the type of operation being performed. For example, RepeatCount
will have default value of ZERO for the expression (5 + RepeatCount).
    The automatic conversion makes it easier to work with different kinds
of data. It isn't necessary to keep track of different variable types or to
use conversion functions. Most of the time, different data types can be used
interchangeably without special consideration. The automatic conversion is
described in the following sections so that predictable results can easily be
achieved.

                                     6-5

Order of Evalution

    Each operator has a "priority" that defermines the order of
computation. For example, multiplication is performed before additon. The
priority scale ranges from 1 to 8, where oparations with a priority of 8 are
performed first and operations with a priority of 1 are last.
    The proirities cause expressions to be evaluated in the standard
order of algabraic rules. Operators with the parenthesis are evaluated first,
following by the next lower priority. Operators with the same priority are
evaluated from left to right. All expressions allow the usage of parenthesis
to change the order of evaluation or to clarity the intended usage.


Numeric Operations

    These operators provide the basic arithmetic functions. They operate
on integer values. If a value is a stirng or logical, it is converted into an
integer.

                Number of
                  Operation    Values    Priority    Symbol
                  ------------------------------------------
        Unary Minus    1    8    -
        Unary Plus    1    8    +
        Multiply        2    6    *
        Divide        2    6    / or %
        Modulo        2    6    MOD or //
        Addition        2    5    +
        Subtract        2    5    -


Unary Operators

    As in algabra, + and - can be used to indicate positive or negative
numbers. A unary operator can precede a single value. The value can be a
constant, a variable or an expression within parentheses. Unary operators have
the highest priority.

    Examples:
        -8    +56    -Count    -( x + y )

Multiply, Divide, Modulo, Add, and Subtract Operators

    These operations perform the basic algebaric operations. The modulo
operation operation returns the remainder of an integer divide. Both the
symbol // or the word MOD can be used.


    Expression    Result
    ------------------------
    4 + 7 - 2    9
    5 + 3 * 2    11
    -8 - 6 / 2    -11
    +6 - 11 MOD 3    4
    +6 -11 // 3    4

NOTE: Currently you can use either / or % for Division. Future releases will
use / for Floating Point Division and % for Interger Division. Your current
scripts will be fully compatable with future versions if you use the %
operator.

                                     6-6

String to Integer Conversion

    If the first characters within the string represents an integer, the
automatic conversion will recognize the value. Otherwise, an integer value of
ZERO will be used.

    Sting        Result
    ------------------------
    "104"        104
    "14 Times"    14
    "Five"        0
    "-86"        -86
    " -5 "        0
    "Jacks"        0


Logical to Integer Conversion

    Logicals are either TRUE or FALSE. TRUE convertes to 1. FALSE
converts to 0.

    Logical        Result
    ------------------------
    TRUE        1
    FALSE        0
    ON        1
    OFF        0
    YES        1
    NO        0
    ( 5 = 6 )    0
    ( 5 <= 6 )    1


Sting Concatenation Operations

    The string concatenation operators append two strings together. The
concatenate including space operator (|||) appends the two strings with a
space between them.

                    Number of
    Operation            Values    Priority    Symbol
    ------------------------------------------------------------
    Concatenate            2    4    ||
    Concatenate including Space    2    4    |||

    Expression        Result
    --------------------------------------
    "1234" || "5678"        "12345678"
    "1234" ||| "5678"        "1234 5678"

                                     6-7

Integer to String Conversion

    If the value for a string operation is an integer, it will be
converted to a string. The string equivalent will not contain leading speces
or zeros. If the integer is negative, it will contain leading minus sign
("-").

    Expression            Result
    ------------------------------------------------------
    "Score:" || 250            "Score:250"
    "Ending Value:" ||| ( 15 - 25 )    "Ending Value:-10"


Logical to String

    If a logical value is used in a string operation, it will be
converted to eithe "TRUE" or "FALSE".

    Expression            Result
    ------------------------------------------------------
    "Value > 100:"||| ( Value > 100 )    "Value > 100: TRUE"
    TRUE ||| FALSE ||| YES ||| NO    "TRUE FALSE TRUE FALSE"


Relational

    Relational operators compare two values to each other. These
operations work with both integer and string values. The result of a
relational comparison is a logical value.

                Number of
    Operation        Values    Priority    Symbol
    ----------------------------------------------------------
    LessThan            2    3    <
    GreaterThan        2    3    >
    LessThan or Equal        2    3    <=  =<
    GreaterThan or Equal    2    3    >=  =>
    NotEqual            2    3    < >  > <  ~ =
    Equal            2    3    =  = =  : =

    If both values are integers, they are compared in the usual way.
However, if either of the values are not integers, then both values are
converted to strings.
    The results of string comparisons are similar to the way a dictionary
is ordered. However, upper and lower case letters are not the same. The order
of the letters are based on the ASCII character set ( see ASCII appendix ).

    Expression        Result
    -----------------------------------------------------
    7 + 2 < 6        FALSE
    5 - 7 ==- ( 12 / 6 )    TRUE
    "Five" <> "FIVE"        TRUE
    "-15" = 5 * -3        TRUE ( string comparison )

                                     6-8

Boolean Operations

    Boolean operations work with logical values. Often they are used with
the results from relational comparisons.

            Number of
    Operation    Values    Priority    Symbol
    ------------------------------------------
    NOT        1    8    NOT  ~
    And        2    2    AND  &
    Or        2    1    OR   |
    Xor        2    1    XOR &&

    The OR operation is used to determine if either of two conditions is
TRUE. The AND operation determines if BOTH conditons are TRUE. The XOR is used
to ascertain when one of the values is TRUE but not BOTH.
    The NOT operation is similar to the unary minus. The unary minus
changes the sign of a value. The NOT operation changes a TRUE value to FALSE,
and a FALSE value to TRUE.

    Expression        IntermediateResult    Result
    ------------------------------------------------------------------
    3 <> 4 or 5 = 6        TRUE or FALSE        TRUE
    5 = 3 + 2 and 7 < 2    TRUE and FALSE        FALSE
    3 <= 7 and -5 >= -8    TRUE and TRUE        TRUE
    not (5 = 5 and 6 <> 7 )    NOT ( TRUE )        FALSE


Integer to Logical Conversion

    When the value for a logical operation is an integer, it will be
converted to FALSE if the value is ZERO. Othewise, it is converted to TRUE.

    Expression    Result
    ------------------------
    0 or 1        TRUE
    1 and 5        TRUE
    NOT 5        FALSE


String to Logical Conversion

    If the value for a logical operation is a string, it is converted to
a TRUE when the STRING is "TRUE","ON", or "YES". The identification is only on
the leading characters of the string. If the leading characters do not match,
it is converted to FALSE.

    Expression    Result
    -------------------------------------------------------
    "TRUE" or "FALSE"    TRUE
    "TRUE" and "ON"    TRUE
    "TRUE" and " ON"    FALSE
    "TRUE" and "ONCE"    TRUE ( "ON" is identified in "ONCE" )

                                     6-9

                                  Functions

    A function is an operation, which returns a single value, that can be
used within an expression.
    Some functions do not require parameters. These functions are called
System Variables. This is because their usage resembles that of variables.
MouseX is an example of a System Variable. It can be used in any expression
just as though is was a variable. However, it is a read-only variable. This
means you can not use the LET Command to change its value. It is always equal
to the "current" value of the horizontal position of the mouse pointer.

    Other functions require information, on the form of parameters, on
order to perform its operation. A function can have one or more parameters,
contained with parenthesis, and separated by commas.

LET X = MAX { OldX , Y / " , 100 }

    This assignment demonstrates the Max Function. The parameter list for
the function is contained within parenthesis. Each parameter is an expression.
This means it can contain constants, variables, operatiors, and even other
functions. Multiple parameters are separated by commas.
    As with operators, the parameters for functions have expected data
types. The parameter is automatically converted to the required type.
    The function returns a single result. This way, the function cn be
placed in an expression just as a variable or constant.


Conversion Functions

    Within expressions, values are automatically converted to the type of
data neeeded for an operation. However, the data type of the result is
detemined by last operation performed.

    <integer> = Integer { expression }
    "string"  = String  { expression }
    «logical» = Logical { expression }

Example:
    LET Count = "123" || "456"

    The variable Count is assigned the string value of "123456". Count
could be successfully used in arithmetic operations. However, each time it is
used it is converted ino an integer. If Count is primarily used as an integer,
it would be more efficient to convert the value when it is assigned.

LET Count = Integer { "123" || "456" }

    The Integer Function converts the value within the parenthesis into
an intege. Likewise, the String and Logical Funcions convert values into
strings and logicals.

                                     6-10

Integer Functions

    The following functions allow you to work with in integer values.

ABSOLUTE        <integer> = ABSOLUTE ( <value> )

    The Absolute Function returns the absolute value of an integer. If
the value is positive or ZERO, ABSOLUTE returns the same value. If the value
is negative, it returns the positive value.

    Expression    Result
    ------------------------
    ABSOLUTE (156)    156
    ABSOLUTE (-66)     66
    ABSOLUTE (0)      0

LIMIT        <integer> = LIMIT ( <limit1> , <limit2> , <test value> )

    The Limit Function returns a value within a specified range. The
first two values, <limit1> and <limit2> indicate the minimun and maximum
values in the range. The thrid parameter is the value to test. If this value
is between the two limits, the Limit Function returns the value unchanged. If
it is less than the low limit, it returns the low limit value. If it is
greater then the high limit, it returns the high limit value.

    Expression        Result
    ---------------------------------
    LIMIT (0,100,89)          89
    LIMIT (-300,-100,45)    -100
    LIMIT (900,400,0)         400

MAX        <intege> = MAX ( <value> { , <value> , ...} )

    The Max Funtion returns the value of the highest parameter. The Max
Function can have one or more parameters.

    Expression        Result
    ---------------------------------
    MAX (6,-1000,66,-5)     66
    MAX (-10,-5)        - 5
    MAX (6-5,7*3,-1)         21

MIN        <integer> = MIN ( <value> { , <value> , ...} )

    The Min Function returns the value of the lowest parameter. The Min
Function can have one or more parameters.

    Expression        Result
    ---------------------------------
    MIN (100,5000,200)     100
    MIN (-5*6,-1)        - 30
    MIN (5,7,-3,10,-5,88,8)    -  5

                                     6-11

RANDOM        <integer> = RANDOM ( <minimum> , <maximum> )

    The Random Function returns a random integer between and including
the <minimum> and <maximum> values.

    Expression    Result
    ---------------------------------------------
    RANDOM (5,20)    any value between 5 and 20.

SIGN        <integer> = SIGN ( <value> )

    The Sign Function returns the sign of the value. If the value is
positive, it returns 1. If the value is ZERO (0), it returns 0, Otherwise, it
returns -1.


String Functions

    The string frunctions allow you to manupulate and work with strings.

ASCII        <integer> = ASCII ( "string" )

    The ASCII Function returns the ASCII value of the first cahracter in
the supplied string. The ASCII value is a positive integer between o and 255.

    Expression    Result
    ------------------------
    ASCII ( "A" )     65
    ASCII ( "m" )    109
    ASCII ( "more" )    109
    ASCII ( "<" )     60

CHAR        "string" = CHAR ( <integer> )

    The Char Function returns a single character string cooresponding to
an ASCII intege. The ASCII values range from 0 to 255.


    Expression    Result
    ------------------------
    CHAR (65)    "A"
    CHAR (109)    "m"
    CHAR (60)    "<"

                                     6-12

NUNBEROFCHARS    <integer> = NUMBEROFCHARS ( "string" )

    The NumberOfChars takes a string parameter, and returns the number of
characters.

    Expression                Result
    ---------------------------------------------------
    NumberOfChars ( "Hello!" )             6
    NumberOfChars ( "Spanish Inquisition" )    20
    NumberOfChars ( -67 )             3

LOWERCASE    "string" = LOWERCASE ( "string" )

    The LowerCase Function converts uppercase characters within a string
to lowercase. All other characters remain unchanged.

    Expression            Result
    --------------------------------------------------
    LOWERCASE ( "ABCdef123#$%" )    "abcdef123#$%"

UPPERCASE    "string" = UPPERCASE ( "string" )

    The UpperCase Function converts lowercase characters within a string
to uppercase. All other characters remain unchanged.

DUPESTRING        "string" = DUPESTRING ( "string" , <count> )

    The DupeString duplicates a string a specified nymber of times. It
returns a single string.

    Expression        Result
    --------------------------------------------------
    DUPESTRING ("*",10)    "**********"
    DUPESTRING ("-",6)    "------"
    DUPESTRING ("Hello! ",3)    "Hello! Hello! Hello! "

TRIMSTRING        "string" = TRIMSTRING ( "string" )

    The TrimString Function removes leading and trailing spaces and TAB
characters within the remaining string are replaced with a single space.

    Expression            Result
    ----------------------------------------------------
    TRIMSTRING (" This is a  Test")    "This is a Test"
    TRIMSTRING ("Hello Out there!  ")    "Hello Out there!"

                                     6-13

INSERTCHARS    "string" = INSERTCHARS ( "source","destination",<offset> )

    The InsertChars Function inserts a source string into the distination
string at the specified offset. If the offset is greater than the length of
the destination string, the source string is appended to the end of the
destination.

    Expression            Result
    -----------------------------------------------
    INSERTCHARS ("...","123456",4)    "1234...56"

REMOVECHARS    "string"=REMOVECHARS ( "source",<starting offset>,<length> )


    The RemoveChars Function returns a string with specified characters
removed. The first parameter is the source string from which to remove the
characters. The second parameter specifies the starting offset of the
characters to be removed. The last parameter indicates the number of
characters to remove.

    Expression            Result
    ------------------------------------------
    REMOVECHARS ("12345",3,2)        "125"
    REMOVECHARS ("Hello!",5,1)        "Hell!"
    REMOVECHARS ("Hello!",5,-1)    "Hello!"

FINDCHARS    <integer> = FINDCHARS ( "source","search",<starting offset> )

    The FindChars Function searches the contents of a source string for a
matching string.
The <starting offset> indicates the offset within the "source" string to begin
the search. The "search" string must match identically. If the string is
found, FindChars returns the offset within the "source" string of the first
character of the matching string. If the string is not found, FindChars
returns a ZERO (0).

    Expression            Result
    ------------------------------------------
    FINDCHARS ("Hello Bill!","Bill",1)    7
    FINDCHARS ("Hello Bill!","Fred",1)    0
    FINDCHARS ("This is it!","is",1)    3
    FINDCHARS ("This is it!","is",4)    5

                                     6-14

GETCHARS        "string" = GETCHARS ( "source",<starting offset>,<length> )

    The GetChars Function returns a portion of a string. The <starting
offset> indicates the starting character of the substring. The <length>
indicates the number of characters to include.

    Expression            Result
    ------------------------------------------
    GETCHARS ("Brainpower",2,4)    "rain"
    GETCHARS ("Hello!",4,10)        "lo!"
    GETCHARS ("Jim Finney",20,1)    ""

FINDWORD        <integer> = FINDWORD ("source","search word"
               {,<startwordnumber> {,"worddelimiters"}})

    The FindWord searches a "source" string for a matching "search word"
and returns its word number. If the word is not found, it will return a ZERO
(0). The optional <StartWordNumber> allows you to specify a starting word
number to begin the search. If it is not specified, it defaults to 1. The
"WordDeflimiters" can contain characters indicating the characters that
separate word.

    Expression                    Result
    ------------------------------------------------------------
    FINDWORD ("This is a sample sentence.","sample")    4

GETWORD        "string" = GETWORD ("source",<wordnumber>
              {,"worddelimiters"})

    The GetWord Function returns a specified word nymber from the
"source" string. The <wordnumber> indicates which word to return. A
<wordnumber> of 1 returns the first word. A 2 returns the second word. By
default, words are separated by spaecs. You can supply a list of characters in
the optional parameter "worddelimiters".



    Expression                Result
    -----------------------------------------------------
    GETWORD ("The dog Smiled.",3)        "Smiled"
    GETWORD ("DF1:Sounds/Bird.snd",2,":/")    "Sounds"

                                     6-15

POSITIONOFWORD    "string" = POSITONOFWORD ("source",<wordnumber>
              {,"worddelimiters"})

    The PositionOfWord Function returns the offset into the "source"
string for a specified word <wordnumber>. If the <wordnumber> is greater than
the number of words in the "source" string, PositionOfWord returns a ZERO (0).
The "worddelimiters" work in the same way as in GetWord allowing you to
specify the charcaters separating words.

    Expression                Result
    ---------------------------------------------------
    POSITONOFWORD ("Word1 Word2 Word3",2)    7

BUMPREVISION    "string" = BUMPREVISION ( "name" )

    The BumpRevision Function changes the revision of a "name" in the
same manner the Workbench Duplicate function does with a filename.

    Expression            Result
    ------------------------------------------
    BUMPREVISION ("Record")        "Copy of Record"
    BUMPREVISION ("Copy of Record")    "Copy 2 of Record"
    BUMPREVISION ("Copy 2 of Record")    "Copy 3 of Record"

EVALUATEEXPRESSION    results = EVALUATEEXPRESSION ( "string" )

    The EvaluateExpression Function evaluates the string parameter. The
string must contain a valid expression. EvaluateExpression returns the result
of the evaluation. If there is any uncertainty as to the validity of the
expression, a run time error can be avoided by using the VerifyExpression
Function.
    This function allows expressions to be created at run time. This can
be quite powerful. However, it is error prone and it can make the script
difficult to read.

    Expression            Result
    ------------------------------------------
    EVALUATEEXPRESSION ("5+6")         11
    EVALUATEEXPRESSION ("123" || "-23")    100

                                     6-16

VERIFYEXPRESSION        «logical» = VERIFYEXPRESSION ( "string" )

    The VerifyExpression Functon evaluates the string parameter. However,
it does not return the resulting value of the evaluation. It returns a TRUE if
the expression is successfully evaluated. Otherwise, it returns a FALSE. This
function also allows an expression to be verified before using the
EvaluteExpression.

    Expression        Result
    ---------------------------------
    VERIFYEXPRESSION ("5+6")    TRUE
    VERIFYEXPRESSION ("6+*7)    FALSE
    VERIFYEXPRESSION ("(5+6")    FALSE